diff --git a/optional-skills/mlops/nvidia/cudaq-guide/SKILL.md b/optional-skills/mlops/nvidia/cudaq-guide/SKILL.md new file mode 100644 index 0000000000000..ca65845393f65 --- /dev/null +++ b/optional-skills/mlops/nvidia/cudaq-guide/SKILL.md @@ -0,0 +1,288 @@ +--- +name: nvidia-cudaq-guide +description: CUDA-Q quantum computing onboarding guide. +version: 1.0.0 +author: NVIDIA CUDA-Q Team +license: Apache-2.0 +platforms: [linux, windows] +metadata: + hermes: + tags: [nvidia, quantum-computing, cuda-q, gpu] + category: mlops +--- + +## CUDA-Q Getting Started Guide + +You are a CUDA-Q expert assistant. Guide the user through the CUDA-Q platform +based on their instructions. If no argument is given, present the full +onboarding menu. + +## Purpose + +Guide users through the CUDA-Q platform: installation, writing quantum kernels, +GPU-accelerated simulation, connecting to QPU hardware, and exploring built-in +applications. + +## Prerequisites + +- Python 3.10+ (for Python installation path) +- CUDA Toolkit (for GPU-accelerated targets on Linux; not required on macOS) +- NVIDIA GPU (optional; CPU-only simulation available via `qpp-cpu`) +- For C++ path: Linux or WSL on Windows +- For QPU access: provider-specific credentials and account + +## Instructions + +- Invoke with `/nvidia-cudaq-guide [argument]` +- If no argument is given, display the full onboarding menu and ask what + the user wants to explore +- Pass an argument from the routing table below to jump directly to that topic +- Read local CUDA-Q documentation files to answer questions accurately + +## References + +| Section | Doc file | +| --- | --- | +| Install | `docs/sphinx/using/install/install.rst`, `docs/sphinx/using/quick_start.rst` | +| Test Program | `docs/sphinx/using/basics/kernel_intro.rst`, `docs/sphinx/using/basics/build_kernel.rst` | +| GPU Simulation | `docs/sphinx/using/backends/sims/svsims.rst`, `docs/sphinx/using/examples/multi_gpu_workflows.rst` | +| QPU | `docs/sphinx/using/backends/hardware.rst`, `docs/sphinx/using/backends/cloud.rst` | +| Applications | `docs/sphinx/using/applications.rst` | +| Parallelize | `docs/sphinx/using/examples/multi_gpu_workflows.rst` | + +## Routing by Argument + +| Argument | Action | +|---|---| +| `install` | Walk through installation (see Install section) | +| `test-program` | Build and run a Bell state kernel to verify CUDA-Q is working properly | +| `gpu-sim` | Explain GPU-accelerated simulation targets (see GPU Simulation section) | +| `qpu` | Explain how to run on real QPU hardware (see QPU section) | +| `applications` | Showcase what can be built with CUDA-Q (see Applications section) | +| `parallelize` | Show how to run circuits in parallel across multiple QPUs (see Parallelize section) | +| _(none)_ | Print the full menu below and ask what they'd like to explore | + +--- + +## Full Menu (no argument) + +Present this when invoked with no argument + +```text +CUDA-Q Getting Started + +CUDA-Q is NVIDIA's unified quantum-classical programming model for CPUs, GPUs, and QPUs. +Supports Python and C++. Docs https://nvidia.github.io/cuda-quantum/ + +Choose a topic + /nvidia-cudaq-guide install Install CUDA-Q (Python pip or C++ binary) + /nvidia-cudaq-guide test-program Write and run your quantum kernel + /nvidia-cudaq-guide gpu-sim Accelerate simulation on NVIDIA GPUs + /nvidia-cudaq-guide qpu Connect to real QPU hardware + /nvidia-cudaq-guide applications Explore what you can build + /nvidia-cudaq-guide parallelize Run circuits in parallel across multiple QPUs +``` + +--- + +## Install + +Instructions + +- Default to Python installation unless the user explicitly mentions C++ or + the `nvq++` compiler. +- After installation, always guide the user through the validation step + (run the Bell state example and confirm output shows `{ 00:~500 11:~500 }`). +- Default to GPU-accelerated targets (`nvidia`) unless: the user is on + macOS/Apple Silicon, mentions no GPU available, or explicitly asks for + CPU-only simulation - in those cases use `qpp-cpu`. +- Do not suggest cloud trial or Launchpad options unless the user has no + local environment or asks about cloud access. + +Platform notes + +- Linux (x86_64, ARM64): full GPU support - + `pip install cudaq` + CUDA Toolkit +- macOS (ARM64/Apple Silicon): CPU simulation only - + `pip install cudaq` (no CUDA Toolkit needed) +- Windows: use WSL, then follow Linux instructions +- C++ (no sudo): + `bash install_cuda_quantum*.$(uname -m) --accept -- --installpath $HOME/.cudaq` +- Brev (cloud, no local setup): Log in at the NVIDIA Application Hub, + open a CUDA-Q workspace, then SSH in with the Brev CLI: + + ```bash + brev open ${WORKSPACE_NAME} + ``` + + CUDA-Q and the CUDA Toolkit are pre-installed. + +--- + +## Test Program + +Key concepts to explain + +- `@cudaq.kernel` / `__qpu__` marks a quantum kernel - compiled to Quake MLIR +- `cudaq.qvector(N)` allocates N qubits in |0⟩ +- `cudaq.sample()` - kernel measures qubits; returns bitstring histogram + (`SampleResult`) +- `cudaq.run()` - kernel returns a classical value; runs `shots_count` times + and returns a list of those return values +- `cudaq.observe()` - computes expectation value ⟨H⟩ for a spin operator +- `cudaq.get_state()` - returns the full statevector (simulator only) + +Kernel restrictions + +- Only a restricted Python subset is valid inside a kernel - it compiles to + Quake MLIR, not regular Python. +- NumPy and SciPy cannot be used inside a kernel. Use them outside the kernel + for classical pre/post-processing. +- Kernels can call other kernels; the callee must also be a `@cudaq.kernel`. + +For compiler internals (`inspect` module -> `ast_bridge.py` -> Quake MLIR -> +QIR -> JIT), route to `/cudaq-compiler`. + +--- + +## GPU Simulation + +To recommend the best simulation backend for the user, consult the full +comparison table at + + +### Available GPU Targets + +| Target | Description | Use when | +|---|---|---| +| `nvidia` (default) | Single-GPU state vector via cuStateVec (up to ~30 qubits) | Default choice for most simulations on a single GPU | +| `nvidia --target-option fp64` | Double-precision single GPU | Higher numerical precision needed (e.g. chemistry, sensitive observables) | +| `nvidia --target-option mgpu` | Multi-GPU, pools memory across GPUs (>30 qubits) | Circuit exceeds single-GPU memory; requires MPI | +| `nvidia --target-option mqpu` | Multi-QPU, one virtual QPU per GPU, parallel execution | Running many independent circuits in parallel (e.g. parameter sweeps, VQE gradients) | +| `tensornet` | Tensor network simulator | Shallow or low-entanglement circuits; qubit count exceeds statevector feasibility | +| `qpp-cpu` | CPU-only fallback (OpenMP) | No GPU available; macOS; small circuits for testing | + +--- + +## QPU + +When the user invokes this section, do not dump all providers at once. +Instead, follow this two-step dialogue: + +Step 1 - ask which technology they want + +```text +Which QPU technology are you targeting? + 1. Ion trap (IonQ, Quantinuum) + 2. Superconducting (IQM, OQC, Anyon, TII, QCI) + 3. Neutral atom (QuEra, Infleqtion, Pasqal) + 4. Cloud / multi-platform (AWS Braket, Scaleway) +``` + +Step 2 - once they pick a technology, ask which provider, then read the +corresponding doc file and walk the user through it step by step. + +| Technology | Provider | Doc file | +|---|---|---| +| Ion trap | IonQ | `docs/sphinx/using/backends/hardware/iontrap.rst` (IonQ section) | +| Ion trap | Quantinuum | `docs/sphinx/using/backends/hardware/iontrap.rst` (Quantinuum section) | +| Superconducting | IQM | `docs/sphinx/using/backends/hardware/superconducting.rst` (IQM section) | +| Superconducting | OQC | `docs/sphinx/using/backends/hardware/superconducting.rst` (OQC section) | +| Superconducting | Anyon | `docs/sphinx/using/backends/hardware/superconducting.rst` (Anyon section) | +| Superconducting | TII | `docs/sphinx/using/backends/hardware/superconducting.rst` (TII section) | +| Superconducting | QCI | `docs/sphinx/using/backends/hardware/superconducting.rst` (QCI section) | +| Neutral atom | Infleqtion | `docs/sphinx/using/backends/hardware/neutralatom.rst` (Infleqtion section) | +| Neutral atom | QuEra | `docs/sphinx/using/backends/hardware/neutralatom.rst` (QuEra section) | +| Neutral atom | Pasqal | `docs/sphinx/using/backends/hardware/neutralatom.rst` (Pasqal section) | +| Cloud | AWS Braket | `docs/sphinx/using/backends/cloud/braket.rst` | +| Cloud | Scaleway | `docs/sphinx/using/backends/cloud/scaleway.rst` | + +After walking through the provider steps, always close with + +- Test locally first with `emulate=True` before submitting to real hardware. +- Use `cudaq.sample_async()` / `cudaq.observe_async()` for non-blocking submission. + +--- + +## Applications + +CUDA-Q ships with ready-to-run application notebooks + +| Category | Examples | +|---|---| +| Optimization | QAOA, ADAPT-QAOA, MaxCut | +| Chemistry | VQE, UCCSD, ADAPT-VQE | +| Error Correction | Surface codes, QEC memory | +| Algorithms | Grover's, Shor's, QFT, Deutsch-Jozsa, HHL | +| ML | Quantum neural networks, kernel methods | +| Simulation | Hamiltonian dynamics, Trotter evolution | +| Finance | Portfolio optimization, Monte Carlo | + +--- + +## Parallelize + +CUDA-Q supports two distinct multi-GPU parallelization strategies - pick based +on what you are trying to scale. + +| Goal | Strategy | Target option | +|---|---|---| +| Single circuit too large for one GPU | Pool GPU memory | `nvidia --target-option mgpu` | +| Many independent circuits at once | Run circuits in parallel | `nvidia --target-option mqpu` | +| Large Hamiltonian expectation value | Distribute terms across GPUs | `mqpu` + `execution=cudaq.parallel.thread` | + +### Circuit batching with mqpu (`sample_async` / `observe_async`) + +The `mqpu` option maps one virtual QPU to each GPU. Dispatch circuits +asynchronously with `qpu_id` to all GPUs simultaneously. + +```python +import cudaq + +cudaq.set_target("nvidia", option="mqpu") +n_qpus = cudaq.get_platform().num_qpus() + +futures = [ + cudaq.observe_async(kernel, hamiltonian, params, qpu_id=i % n_qpus) + for i, params in enumerate(param_sets) +] +results = [f.get().expectation() for f in futures] +``` + +### Hamiltonian batching + +For a single kernel with a large Hamiltonian, add `execution=` to +`cudaq.observe` — no other code change needed. + +```python +# Single node, multiple GPUs +result = cudaq.observe(kernel, hamiltonian, *args, + execution=cudaq.parallel.thread) + +# Multi-node via MPI +result = cudaq.observe(kernel, hamiltonian, *args, + execution=cudaq.parallel.mpi) +``` + +See the docs above for complete working examples of both patterns. + +--- + +## Limitations + +- GPU simulation requires Linux (x86_64 or ARM64); macOS is CPU-only +- Multi-GPU `mgpu` target requires MPI +- Kernel code must use a restricted Python subset; NumPy/SciPy are not + allowed inside kernels +- QPU access requires provider-specific credentials and accounts + +## Troubleshooting + +- Import error after `pip install cudaq`: Ensure Python 3.10+ and a + supported OS (Linux or macOS) +- No GPU detected: Verify CUDA Toolkit is installed and `nvidia-smi` + shows your GPU; fall back to `qpp-cpu` +- Kernel compile error: Check that only supported Python constructs are + used inside `@cudaq.kernel` +- QPU submission fails: Confirm credentials are set as environment + variables per the provider docs diff --git a/optional-skills/mlops/nvidia/cuopt-numerical-optimization-api-python/SKILL.md b/optional-skills/mlops/nvidia/cuopt-numerical-optimization-api-python/SKILL.md new file mode 100644 index 0000000000000..50b3fd1d3ebb9 --- /dev/null +++ b/optional-skills/mlops/nvidia/cuopt-numerical-optimization-api-python/SKILL.md @@ -0,0 +1,286 @@ +--- +name: nvidia-cuopt-numerical-optimization-api-python +description: GPU-accelerated linear and integer programming. +version: 26.08.00 +author: NVIDIA +license: Apache-2.0 +platforms: [linux, windows] +metadata: + hermes: + tags: [nvidia, optimization, gpu, linear-programming, milp] + category: mlops + related_skills: [huggingface-hub] +--- + +# cuOpt Numerical Optimization Skill (Python) + +Model and solve LP, MILP, and QP problems using NVIDIA cuOpt's GPU-accelerated solver. The Python API surface (`Problem`, `SolverSettings`, `solve`) is shared across all three problem classes — only the objective form and a few rules change. + +## Before You Start + +Use a formulation summary (parameters, constraints, decisions, objective) if available; otherwise ask for decision variables, objective, and constraints. Then confirm **problem type** (LP / MILP / QP — see below) and **variable types**. + +## Choosing LP vs MILP vs QP + +**Decide from the objective and variables:** + +| If the objective is... | And variables are... | Use | +|---|---|---| +| Linear (sum of `c_i * x_i`) | All continuous | **LP** | +| Linear | Some integer or binary | **MILP** | +| Has squared (`x*x`) or cross (`x*y`) terms | Continuous (integer QP not supported) | **QP** (beta) | + +**Prefer LP when the problem allows it.** LP solves faster and has stronger optimality guarantees. Use MILP only when the problem logically requires whole numbers or yes/no decisions. Use QP only when the objective is genuinely quadratic (variance, squared error, kinetic energy). + +**Problem types that need extra care:** Multi-period planning and goal programming are easy to misinterpret. Double-check that rates and constraints apply to the right time period or priority level (AGENTS.md: verify understanding before code). + +- **Use LP** when every quantity can meaningfully be fractional: flows, proportions, rates, dollars, hours, tonnes of material, etc. +- **Use MILP** when the problem mentions **counts** of discrete entities, **yes/no** choices, or **either/or** decisions (e.g. open a facility or not, assign a person to a shift, number of trucks). +- **Use QP** when the objective minimizes variance, squared error, or any expression with `x*x` or `x*y` terms (portfolio optimization, least squares, regularized regression). + +## Integer vs continuous from wording + +Choose variable type from what the problem describes. + +| Problem wording / concept | Variable type | Examples | +|---------------------------|---------------|----------| +| **Discrete entities (counts)** | **INTEGER** | Workers, cars, trucks, machines, pilots, facilities, units to manufacture (when "units" means whole items), trainees, vehicles | +| **Yes/no or on/off** | **INTEGER** (binary, lb=0 ub=1) | Open a facility, run a machine, produce a product line, assign a person to a shift | +| **Amounts that can be fractional** | **CONTINUOUS** | Tonnes, litres, dollars, hours, kWh, proportion of capacity, flow volume, weight | +| **Rates or fractions** | **CONTINUOUS** | Utilization, percentage, share of budget | +| **Unclear** | Prefer **INTEGER** if the noun is a countable thing (a worker, a car); prefer **CONTINUOUS** if it's a measure (amount of steel, hours worked). If the problem says "whole" or "integer" or "number of", use INTEGER. | + +**Rule of thumb:** If the quantity is "how many *things*" (people, vehicles, items, sites), use **INTEGER**. If it's "how much" (mass, volume, money, time) or a rate, use **CONTINUOUS** unless the problem explicitly requires whole numbers. + +## Quick Reference: Python API + +### LP Example + +```python +from cuopt.linear_programming.problem import Problem, CONTINUOUS, MAXIMIZE +from cuopt.linear_programming.solver_settings import SolverSettings + +# Create problem +problem = Problem("MyLP") + +# Decision variables +x = problem.addVariable(lb=0, vtype=CONTINUOUS, name="x") +y = problem.addVariable(lb=0, vtype=CONTINUOUS, name="y") + +# Constraints +problem.addConstraint(2*x + 3*y <= 120, name="resource_a") +problem.addConstraint(4*x + 2*y <= 100, name="resource_b") + +# Objective +problem.setObjective(40*x + 30*y, sense=MAXIMIZE) + +# Solve +settings = SolverSettings() +settings.set_parameter("time_limit", 60) +problem.solve(settings) + +# Check status (CRITICAL: use PascalCase!) +if problem.Status.name in ["Optimal", "PrimalFeasible"]: + print(f"Objective: {problem.ObjValue}") + print(f"x = {x.getValue()}") + print(f"y = {y.getValue()}") +``` + +### MILP Example (with integer variables) + +```python +from cuopt.linear_programming.problem import Problem, CONTINUOUS, INTEGER, MINIMIZE + +problem = Problem("FacilityLocation") + +# Binary variable (integer with bounds 0-1) +open_facility = problem.addVariable(lb=0, ub=1, vtype=INTEGER, name="open") + +# Continuous variable +production = problem.addVariable(lb=0, vtype=CONTINUOUS, name="production") + +# Linking constraint: can only produce if facility is open +problem.addConstraint(production <= 1000 * open_facility, name="link") + +# Objective: fixed cost + variable cost +problem.setObjective(500*open_facility + 2*production, sense=MINIMIZE) + +# MILP-specific settings +settings = SolverSettings() +settings.set_parameter("time_limit", 120) +settings.set_parameter("mip_relative_gap", 0.01) # 1% optimality gap + +problem.solve(settings) + +# Check status +if problem.Status.name in ["Optimal", "FeasibleFound"]: + print(f"Open facility: {open_facility.getValue() > 0.5}") + print(f"Production: {production.getValue()}") +``` + +### QP Example (beta — MINIMIZE only) + +```python +from cuopt.linear_programming.problem import Problem, CONTINUOUS, MINIMIZE +from cuopt.linear_programming.solver_settings import SolverSettings + +# Portfolio variance minimization +problem = Problem("Portfolio") +x1 = problem.addVariable(lb=0, ub=1, vtype=CONTINUOUS, name="stock_a") +x2 = problem.addVariable(lb=0, ub=1, vtype=CONTINUOUS, name="stock_b") +x3 = problem.addVariable(lb=0, ub=1, vtype=CONTINUOUS, name="stock_c") + +# Quadratic objective (variance) — MUST be MINIMIZE +problem.setObjective( + 0.04*x1*x1 + 0.02*x2*x2 + 0.01*x3*x3 + + 0.02*x1*x2 + 0.01*x1*x3 + 0.016*x2*x3, + sense=MINIMIZE, +) + +# Linear constraints +problem.addConstraint(x1 + x2 + x3 == 1, name="budget") +problem.addConstraint(0.12*x1 + 0.08*x2 + 0.05*x3 >= 0.08, name="min_return") + +problem.solve(SolverSettings()) +if problem.Status.name in ["Optimal", "PrimalFeasible"]: + print(f"Variance: {problem.ObjValue}") +``` + +**QP rules:** +- **MINIMIZE only** — solver rejects MAXIMIZE for quadratic objectives. To maximize `f(x)`, minimize `-f(x)`. +- **Continuous variables only** — integer QP is not supported. +- **Q should be PSD** (positive semi-definite) for a convex problem; otherwise the solver may return a non-optimal stationary point. +- **Beta** — API may evolve; treat as production-capable for typical convex QP but expect occasional changes. + +See `resources/qp_examples.md` for least-squares, maximization-workaround, and matrix-form examples. + +## CRITICAL: Status Checking + +**Status values use PascalCase, NOT ALL_CAPS:** + +```python +# ✅ CORRECT +if problem.Status.name in ["Optimal", "FeasibleFound"]: + print(problem.ObjValue) + +# ❌ WRONG - will silently fail! +if problem.Status.name == "OPTIMAL": # Never matches! + print(problem.ObjValue) +``` + +**LP Status Values:** `Optimal`, `NoTermination`, `NumericalError`, `PrimalInfeasible`, `DualInfeasible`, `IterationLimit`, `TimeLimit`, `PrimalFeasible` + +**MILP Status Values:** `Optimal`, `FeasibleFound`, `Infeasible`, `Unbounded`, `TimeLimit`, `NoTermination` + +**QP Status Values:** Same set as LP. For QP debugging, print `f"Actual status: '{problem.Status.name}'"` and check that `Q` is PSD and variables are reasonably scaled. + +## Common Modeling Patterns + +### Binary Selection +```python +# Select exactly k items from n +items = [problem.addVariable(lb=0, ub=1, vtype=INTEGER) for _ in range(n)] +problem.addConstraint(sum(items) == k) +``` + +### Big-M Linking +```python +# If y=1, then x <= 100; if y=0, x can be anything up to M +M = 10000 +problem.addConstraint(x <= 100 + M*(1 - y)) +``` + +### If-then "must also produce" +When the problem says *if we do X then we must also do Y*, enforce both (i) the binary link and (ii) that Y is actually produced: +```python +# y_X <= y_Y (if we do X, we must "do" Y) +problem.addConstraint(y_X <= y_Y) +# Production of Y when Y is chosen: produce at least 1 (or a minimum) when y_Y=1 +problem.addConstraint(production_Y >= 1 * y_Y) # or min_amount * y_Y +``` +Otherwise the solver can set y_Y=1 but production_Y=0, satisfying the binary link but not the intent. + +### Building large expressions +Chained `+` over many terms can hit recursion limits in the API. Prefer building objectives and constraints with **LinearExpression**: +```python +from cuopt.linear_programming.problem import LinearExpression + +# Build as list of (vars, coeffs) instead of v1*c1 + v2*c2 + ... +vars_list = [x, y, z] +coeffs_list = [1.0, 2.0, 3.0] +expr = LinearExpression(vars_list, coeffs_list, constant=0.0) +problem.addConstraint(expr <= 100) +``` +See reference models in this skill's `assets/` for examples. + +### Piecewise Linear (SOS2) +```python +# Approximate nonlinear function with breakpoints +# Use lambda variables that sum to 1, at most 2 adjacent non-zero +``` + +## Solver Settings + +```python +settings = SolverSettings() + +# Time limit +settings.set_parameter("time_limit", 60) + +# MILP gap tolerance (stop when within X% of optimal) +settings.set_parameter("mip_relative_gap", 0.01) + +# Logging +settings.set_parameter("log_to_console", 1) +``` + +## Common Issues + +| Problem | Likely Cause | Fix | +|---------|--------------|-----| +| Status never "OPTIMAL" | Using wrong case | Use `"Optimal"` not `"OPTIMAL"` | +| Integer var has fractional value | Defined as CONTINUOUS | Use `vtype=INTEGER` | +| Infeasible | Conflicting constraints | Check constraint logic | +| Unbounded | Missing bounds | Add variable bounds | +| Slow solve | Large problem | Set time limit, increase gap tolerance | +| Maximum recursion depth | Building big expr with chained `+` | Use `LinearExpression(vars_list, coeffs_list, constant)` | +| QP rejected with MAXIMIZE | QP only supports MINIMIZE | Negate the objective: minimize `-f(x)` | +| QP returns non-optimal | Q not PSD or variables badly scaled | Check Q is PSD; rescale variables to similar magnitudes | + +## Getting Dual Values (LP only) + +```python +if problem.Status.name == "Optimal": + constraint = problem.getConstraint("resource_a") + shadow_price = constraint.DualValue + print(f"Shadow price: {shadow_price}") +``` + +## Reference Models + +All reference models live in this skill's **`assets/`** directory. Use them as reference when building new applications; do not edit them in place. + +### Minimal / canonical examples (LP, MILP, QP) +| Model | Type | Description | +|-------|------|-------------| +| [lp_basic](assets/lp_basic/) | LP | Minimal LP: variables, constraints, objective, solve | +| [lp_duals](assets/lp_duals/) | LP | Dual values and reduced costs | +| [lp_warmstart](assets/lp_warmstart/) | LP | PDLP warmstart for similar problems | +| [milp_basic](assets/milp_basic/) | MILP | Minimal MIP; includes incumbent callback example | +| [milp_production_planning](assets/milp_production_planning/) | MILP | Production planning with resource constraints | +| [portfolio](assets/portfolio/) | QP | Minimize portfolio variance; budget and min-return constraints | +| [least_squares](assets/least_squares/) | QP | Minimize (x-3)² + (y-4)² (closest point) | +| [maximization_workaround](assets/maximization_workaround/) | QP | Maximize quadratic via minimize -f(x) | + +### Other reference +| Model | Type | Description | +|-------|------|-------------| +| [mps_solver](assets/mps_solver/) | LP/MILP | Solve any problem from standard MPS file format | + +**Quick command to list models:** `ls assets/` (from this skill's directory). + +## When to Escalate + +Use troubleshooting and diagnostic guidance if: +- Infeasible and you can't determine why +- Numerical issues diff --git a/optional-skills/mlops/nvidia/cuopt-numerical-optimization-api-python/assets/README.md b/optional-skills/mlops/nvidia/cuopt-numerical-optimization-api-python/assets/README.md new file mode 100644 index 0000000000000..e2b34eccc1d7b --- /dev/null +++ b/optional-skills/mlops/nvidia/cuopt-numerical-optimization-api-python/assets/README.md @@ -0,0 +1,17 @@ +# Assets — reference models + +LP, MILP, and QP reference implementations. Use as reference when building new applications; do not edit in place. + +| Model | Type | +|-------|------| +| lp_basic | LP | +| lp_duals | LP | +| lp_warmstart | LP | +| milp_basic | MILP | +| milp_production_planning | MILP | +| mps_solver | LP/MILP | +| portfolio | QP | +| least_squares | QP | +| maximization_workaround | QP | + +**Run:** From each subdir, `python model.py`. QP is **beta** and supports **MINIMIZE** only. See [resources/qp_examples.md](../resources/qp_examples.md) for additional QP examples. diff --git a/optional-skills/mlops/nvidia/cuopt-numerical-optimization-api-python/assets/least_squares/README.md b/optional-skills/mlops/nvidia/cuopt-numerical-optimization-api-python/assets/least_squares/README.md new file mode 100644 index 0000000000000..5592ff2ac0c96 --- /dev/null +++ b/optional-skills/mlops/nvidia/cuopt-numerical-optimization-api-python/assets/least_squares/README.md @@ -0,0 +1,5 @@ +# Least squares (QP) + +Minimize (x-3)² + (y-4)² — find point closest to (3, 4). Unconstrained quadratic. + +**Run:** `python model.py` diff --git a/optional-skills/mlops/nvidia/cuopt-numerical-optimization-api-python/assets/least_squares/model.py b/optional-skills/mlops/nvidia/cuopt-numerical-optimization-api-python/assets/least_squares/model.py new file mode 100644 index 0000000000000..822d6397d2899 --- /dev/null +++ b/optional-skills/mlops/nvidia/cuopt-numerical-optimization-api-python/assets/least_squares/model.py @@ -0,0 +1,24 @@ +# SPDX-FileCopyrightText: Copyright (c) 2025-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 + +""" +Least squares: minimize (x-3)² + (y-4)². Solution should be x=3, y=4. +""" + +from cuopt.linear_programming.problem import Problem, CONTINUOUS, MINIMIZE +from cuopt.linear_programming.solver_settings import SolverSettings + +problem = Problem("LeastSquares") + +x = problem.addVariable(lb=-100, ub=100, vtype=CONTINUOUS, name="x") +y = problem.addVariable(lb=-100, ub=100, vtype=CONTINUOUS, name="y") + +problem.setObjective(x * x + y * y - 6 * x - 8 * y + 25, sense=MINIMIZE) + +problem.solve(SolverSettings()) + +if problem.Status.name in ["Optimal", "PrimalFeasible"]: + print(f"x = {x.getValue():.4f}") + print(f"y = {y.getValue():.4f}") +else: + print(f"Status: {problem.Status.name}") diff --git a/optional-skills/mlops/nvidia/cuopt-numerical-optimization-api-python/assets/lp_basic/README.md b/optional-skills/mlops/nvidia/cuopt-numerical-optimization-api-python/assets/lp_basic/README.md new file mode 100644 index 0000000000000..4c06f2ded62a9 --- /dev/null +++ b/optional-skills/mlops/nvidia/cuopt-numerical-optimization-api-python/assets/lp_basic/README.md @@ -0,0 +1,7 @@ +# Minimal LP + +Basic linear program: continuous variables, linear constraints, maximize objective. + +**Problem:** Maximize x + y subject to x + y ≤ 10, x − y ≥ 0, x, y ≥ 0. + +**Run:** `python model.py` diff --git a/optional-skills/mlops/nvidia/cuopt-numerical-optimization-api-python/assets/lp_basic/model.py b/optional-skills/mlops/nvidia/cuopt-numerical-optimization-api-python/assets/lp_basic/model.py new file mode 100644 index 0000000000000..d81c6a749d457 --- /dev/null +++ b/optional-skills/mlops/nvidia/cuopt-numerical-optimization-api-python/assets/lp_basic/model.py @@ -0,0 +1,36 @@ +# SPDX-FileCopyrightText: Copyright (c) 2025-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 + +""" +Minimal LP: variables, constraints, objective, solve. + +Problem: + Maximize: x + y + Subject to: x + y <= 10, x - y >= 0, x, y >= 0 +""" + +from cuopt.linear_programming.problem import Problem, CONTINUOUS, MAXIMIZE +from cuopt.linear_programming.solver_settings import SolverSettings + + +def main(): + problem = Problem("Simple LP") + x = problem.addVariable(lb=0, vtype=CONTINUOUS, name="x") + y = problem.addVariable(lb=0, vtype=CONTINUOUS, name="y") + problem.addConstraint(x + y <= 10, name="c1") + problem.addConstraint(x - y >= 0, name="c2") + problem.setObjective(x + y, sense=MAXIMIZE) + + settings = SolverSettings() + settings.set_parameter("time_limit", 60) + problem.solve(settings) + + if problem.Status.name in ["Optimal", "PrimalFeasible"]: + print(f"Objective: {problem.ObjValue}") + print(f"x = {x.getValue()}, y = {y.getValue()}") + else: + print(f"Status: {problem.Status.name}") + + +if __name__ == "__main__": + main() diff --git a/optional-skills/mlops/nvidia/cuopt-numerical-optimization-api-python/assets/lp_duals/README.md b/optional-skills/mlops/nvidia/cuopt-numerical-optimization-api-python/assets/lp_duals/README.md new file mode 100644 index 0000000000000..f0eb9bcf8b748 --- /dev/null +++ b/optional-skills/mlops/nvidia/cuopt-numerical-optimization-api-python/assets/lp_duals/README.md @@ -0,0 +1,7 @@ +# LP Duals and Reduced Costs + +Retrieve dual values (shadow prices) and reduced costs after solving an LP. + +**Problem:** Minimize 3x + 2y + 5z subject to x + y + z = 4, 2x + y + z = 5, x, y, z ≥ 0. + +**Run:** `python model.py` diff --git a/optional-skills/mlops/nvidia/cuopt-numerical-optimization-api-python/assets/lp_duals/model.py b/optional-skills/mlops/nvidia/cuopt-numerical-optimization-api-python/assets/lp_duals/model.py new file mode 100644 index 0000000000000..4fa6a50a5b526 --- /dev/null +++ b/optional-skills/mlops/nvidia/cuopt-numerical-optimization-api-python/assets/lp_duals/model.py @@ -0,0 +1,38 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 + +""" +LP with dual values and reduced costs. + +Problem: + Minimize: 3x + 2y + 5z + Subject to: x + y + z = 4, 2x + y + z = 5, x, y, z >= 0 +""" + +from cuopt.linear_programming.problem import Problem, MINIMIZE + + +def main(): + problem = Problem("min_dual_rc") + x = problem.addVariable(lb=0.0, name="x") + y = problem.addVariable(lb=0.0, name="y") + z = problem.addVariable(lb=0.0, name="z") + problem.addConstraint(x + y + z == 4.0, name="c1") + problem.addConstraint(2.0 * x + y + z == 5.0, name="c2") + problem.setObjective(3.0 * x + 2.0 * y + 5.0 * z, sense=MINIMIZE) + problem.solve() + + if problem.Status.name in ["Optimal", "PrimalFeasible"]: + print(f"Objective: {problem.ObjValue}") + for v in problem.getVariables(): + print( + f"{v.VariableName} = {v.Value}, ReducedCost = {v.ReducedCost}" + ) + for c in problem.getConstraints(): + print(f"{c.ConstraintName} DualValue = {c.DualValue}") + else: + print(f"Status: {problem.Status.name}") + + +if __name__ == "__main__": + main() diff --git a/optional-skills/mlops/nvidia/cuopt-numerical-optimization-api-python/assets/lp_warmstart/README.md b/optional-skills/mlops/nvidia/cuopt-numerical-optimization-api-python/assets/lp_warmstart/README.md new file mode 100644 index 0000000000000..000e7a42fac1f --- /dev/null +++ b/optional-skills/mlops/nvidia/cuopt-numerical-optimization-api-python/assets/lp_warmstart/README.md @@ -0,0 +1,5 @@ +# LP PDLP Warmstart + +Use warmstart data from a solved LP to solve a similar problem faster. LP only (not MILP). + +**Run:** `python model.py` diff --git a/optional-skills/mlops/nvidia/cuopt-numerical-optimization-api-python/assets/lp_warmstart/model.py b/optional-skills/mlops/nvidia/cuopt-numerical-optimization-api-python/assets/lp_warmstart/model.py new file mode 100644 index 0000000000000..b0e893118fc60 --- /dev/null +++ b/optional-skills/mlops/nvidia/cuopt-numerical-optimization-api-python/assets/lp_warmstart/model.py @@ -0,0 +1,52 @@ +# SPDX-FileCopyrightText: Copyright (c) 2025-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 + +""" +PDLP warmstart: solve a similar LP faster by reusing solution context. + +Warmstart is for LP only, not MILP. +""" + +from cuopt.linear_programming.problem import Problem, CONTINUOUS, MAXIMIZE +from cuopt.linear_programming.solver.solver_parameters import ( + CUOPT_METHOD, + CUOPT_PDLP_SOLVER_MODE, +) +from cuopt.linear_programming.solver_settings import ( + SolverSettings, + SolverMethod, + PDLPSolverMode, +) + + +def main(): + print("=== Problem 1 ===") + problem = Problem("LP1") + x = problem.addVariable(lb=0, vtype=CONTINUOUS, name="x") + y = problem.addVariable(lb=0, vtype=CONTINUOUS, name="y") + problem.addConstraint(4 * x + 10 * y <= 130, name="c1") + problem.addConstraint(8 * x - 3 * y >= 40, name="c2") + problem.setObjective(2 * x + y, sense=MAXIMIZE) + + settings = SolverSettings() + settings.set_parameter(CUOPT_METHOD, SolverMethod.PDLP) + settings.set_parameter(CUOPT_PDLP_SOLVER_MODE, PDLPSolverMode.Stable2) + problem.solve(settings) + print(f"Objective: {problem.ObjValue}") + + warmstart_data = problem.getWarmstartData() + print("\n=== Problem 2 (with warmstart) ===") + new_problem = Problem("LP2") + x = new_problem.addVariable(lb=0, vtype=CONTINUOUS, name="x") + y = new_problem.addVariable(lb=0, vtype=CONTINUOUS, name="y") + new_problem.addConstraint(4 * x + 10 * y <= 100, name="c1") + new_problem.addConstraint(8 * x - 3 * y >= 50, name="c2") + new_problem.setObjective(2 * x + y, sense=MAXIMIZE) + settings.set_pdlp_warm_start_data(warmstart_data) + new_problem.solve(settings) + if new_problem.Status.name in ["Optimal", "PrimalFeasible"]: + print(f"Objective: {new_problem.ObjValue}") + + +if __name__ == "__main__": + main() diff --git a/optional-skills/mlops/nvidia/cuopt-numerical-optimization-api-python/assets/maximization_workaround/README.md b/optional-skills/mlops/nvidia/cuopt-numerical-optimization-api-python/assets/maximization_workaround/README.md new file mode 100644 index 0000000000000..bcd0f2c3c19b6 --- /dev/null +++ b/optional-skills/mlops/nvidia/cuopt-numerical-optimization-api-python/assets/maximization_workaround/README.md @@ -0,0 +1,5 @@ +# Maximization workaround (QP) + +QP supports MINIMIZE only. To maximize f(x), minimize -f(x); then negate the optimal value. + +**Run:** `python model.py` diff --git a/optional-skills/mlops/nvidia/cuopt-numerical-optimization-api-python/assets/maximization_workaround/model.py b/optional-skills/mlops/nvidia/cuopt-numerical-optimization-api-python/assets/maximization_workaround/model.py new file mode 100644 index 0000000000000..e18aa613d8ad2 --- /dev/null +++ b/optional-skills/mlops/nvidia/cuopt-numerical-optimization-api-python/assets/maximization_workaround/model.py @@ -0,0 +1,22 @@ +# SPDX-FileCopyrightText: Copyright (c) 2025-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 + +""" +Maximize -x² + 4x (max at x=2) by minimizing x² - 4x; then report -objective. +""" + +from cuopt.linear_programming.problem import Problem, CONTINUOUS, MINIMIZE + +problem = Problem("MaxWorkaround") + +x = problem.addVariable(lb=0, ub=10, vtype=CONTINUOUS, name="x") +problem.setObjective(x * x - 4 * x, sense=MINIMIZE) + +problem.solve() + +if problem.Status.name in ["Optimal", "PrimalFeasible"]: + print(f"x = {x.getValue():.4f}") + print(f"Minimized value = {problem.ObjValue:.4f}") + print(f"Original maximum = {-problem.ObjValue:.4f}") +else: + print(f"Status: {problem.Status.name}") diff --git a/optional-skills/mlops/nvidia/cuopt-numerical-optimization-api-python/assets/milp_basic/README.md b/optional-skills/mlops/nvidia/cuopt-numerical-optimization-api-python/assets/milp_basic/README.md new file mode 100644 index 0000000000000..45362da09bf0c --- /dev/null +++ b/optional-skills/mlops/nvidia/cuopt-numerical-optimization-api-python/assets/milp_basic/README.md @@ -0,0 +1,10 @@ +# Minimal MILP + +Basic mixed-integer program: integer variables with bounds, linear constraints. + +**Problem:** Maximize 5x + 3y subject to 2x + 4y ≥ 230, 3x + 2y ≤ 190, 10 ≤ y ≤ 50, x, y integer. + +- **model.py** — solve and print solution. +- **incumbent_callback.py** — same problem with a callback that prints intermediate (incumbent) solutions during solve. + +**Run:** `python model.py` or `python incumbent_callback.py` diff --git a/optional-skills/mlops/nvidia/cuopt-numerical-optimization-api-python/assets/milp_basic/incumbent_callback.py b/optional-skills/mlops/nvidia/cuopt-numerical-optimization-api-python/assets/milp_basic/incumbent_callback.py new file mode 100644 index 0000000000000..38f553f7e18c3 --- /dev/null +++ b/optional-skills/mlops/nvidia/cuopt-numerical-optimization-api-python/assets/milp_basic/incumbent_callback.py @@ -0,0 +1,50 @@ +# SPDX-FileCopyrightText: Copyright (c) 2025-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 + +""" +Same MILP as model.py but with a callback to receive incumbent (intermediate) solutions. +MILP only; not for LP. +""" + +from cuopt.linear_programming.problem import Problem, INTEGER, MAXIMIZE +from cuopt.linear_programming.solver_settings import SolverSettings +from cuopt.linear_programming.solver.solver_parameters import CUOPT_TIME_LIMIT +from cuopt.linear_programming.internals import GetSolutionCallback + + +class IncumbentCallback(GetSolutionCallback): + def __init__(self, problem, variables, user_data): + super().__init__() + self.problem = problem + self.variables = variables + self.n_callbacks = 0 + self.user_data = user_data + + def get_solution(self, solution, solution_cost, solution_bound, user_data): + self.n_callbacks += 1 + values = self.problem.getIncumbentValues(solution, self.variables) + cost = float(solution_cost[0]) + vals_str = ", ".join(f"{float(v)}" for v in values) + print(f"Incumbent {self.n_callbacks}: [{vals_str}], cost: {cost:.2f}") + + +def main(): + problem = Problem("Incumbent Example") + x = problem.addVariable(vtype=INTEGER) + y = problem.addVariable(vtype=INTEGER) + problem.addConstraint(2 * x + 4 * y >= 230) + problem.addConstraint(3 * x + 2 * y <= 190) + problem.setObjective(5 * x + 3 * y, sense=MAXIMIZE) + + user_data = {"source": "incumbent_callback"} + settings = SolverSettings() + callback = IncumbentCallback(problem, [x, y], user_data) + settings.set_mip_callback(callback, user_data) + settings.set_parameter(CUOPT_TIME_LIMIT, 30) + problem.solve(settings) + + print(f"Status: {problem.Status.name}, Objective: {problem.ObjValue}") + + +if __name__ == "__main__": + main() diff --git a/optional-skills/mlops/nvidia/cuopt-numerical-optimization-api-python/assets/milp_basic/model.py b/optional-skills/mlops/nvidia/cuopt-numerical-optimization-api-python/assets/milp_basic/model.py new file mode 100644 index 0000000000000..5c0bf88e15af6 --- /dev/null +++ b/optional-skills/mlops/nvidia/cuopt-numerical-optimization-api-python/assets/milp_basic/model.py @@ -0,0 +1,36 @@ +# SPDX-FileCopyrightText: Copyright (c) 2025-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 + +""" +Minimal MILP: integer variables with bounds, linear constraints. + +Problem: + Maximize: 5x + 3y + Subject to: 2x + 4y >= 230, 3x + 2y <= 190, 10 <= y <= 50, x, y integer +""" + +from cuopt.linear_programming.problem import Problem, INTEGER, MAXIMIZE +from cuopt.linear_programming.solver_settings import SolverSettings + + +def main(): + problem = Problem("Simple MIP") + x = problem.addVariable(vtype=INTEGER, name="V_x") + y = problem.addVariable(lb=10, ub=50, vtype=INTEGER, name="V_y") + problem.addConstraint(2 * x + 4 * y >= 230, name="C1") + problem.addConstraint(3 * x + 2 * y <= 190, name="C2") + problem.setObjective(5 * x + 3 * y, sense=MAXIMIZE) + + settings = SolverSettings() + settings.set_parameter("time_limit", 60) + problem.solve(settings) + + if problem.Status.name in ["Optimal", "FeasibleFound"]: + print(f"Objective: {problem.ObjValue}") + print(f"x = {x.getValue()}, y = {y.getValue()}") + else: + print(f"Status: {problem.Status.name}") + + +if __name__ == "__main__": + main() diff --git a/optional-skills/mlops/nvidia/cuopt-numerical-optimization-api-python/assets/milp_production_planning/README.md b/optional-skills/mlops/nvidia/cuopt-numerical-optimization-api-python/assets/milp_production_planning/README.md new file mode 100644 index 0000000000000..42a2a1a9d593c --- /dev/null +++ b/optional-skills/mlops/nvidia/cuopt-numerical-optimization-api-python/assets/milp_production_planning/README.md @@ -0,0 +1,5 @@ +# Production Planning (MILP) + +Two products (A, B), resource limits (machine time, labor, material), minimum production, maximize profit. + +**Run:** `python model.py` diff --git a/optional-skills/mlops/nvidia/cuopt-numerical-optimization-api-python/assets/milp_production_planning/model.py b/optional-skills/mlops/nvidia/cuopt-numerical-optimization-api-python/assets/milp_production_planning/model.py new file mode 100644 index 0000000000000..72ded8164dc45 --- /dev/null +++ b/optional-skills/mlops/nvidia/cuopt-numerical-optimization-api-python/assets/milp_production_planning/model.py @@ -0,0 +1,33 @@ +# SPDX-FileCopyrightText: Copyright (c) 2025-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 + +""" +Production planning: two products, resource limits (machine, labor, material), maximize profit. +""" + +from cuopt.linear_programming.problem import Problem, INTEGER, MAXIMIZE +from cuopt.linear_programming.solver_settings import SolverSettings + + +def main(): + problem = Problem("Production Planning") + x1 = problem.addVariable(lb=10, vtype=INTEGER, name="Product_A") + x2 = problem.addVariable(lb=15, vtype=INTEGER, name="Product_B") + problem.addConstraint(2 * x1 + x2 <= 100, name="Machine_Time") + problem.addConstraint(x1 + 3 * x2 <= 120, name="Labor_Hours") + problem.addConstraint(4 * x1 + 2 * x2 <= 200, name="Material") + problem.setObjective(50 * x1 + 30 * x2, sense=MAXIMIZE) + + settings = SolverSettings() + settings.set_parameter("time_limit", 30) + problem.solve(settings) + + if problem.Status.name in ["Optimal", "FeasibleFound"]: + print(f"Product A: {x1.getValue()}, Product B: {x2.getValue()}") + print(f"Total profit: {problem.ObjValue}") + else: + print(f"Status: {problem.Status.name}") + + +if __name__ == "__main__": + main() diff --git a/optional-skills/mlops/nvidia/cuopt-numerical-optimization-api-python/assets/mps_solver/README.md b/optional-skills/mlops/nvidia/cuopt-numerical-optimization-api-python/assets/mps_solver/README.md new file mode 100644 index 0000000000000..f18f4f549e0e0 --- /dev/null +++ b/optional-skills/mlops/nvidia/cuopt-numerical-optimization-api-python/assets/mps_solver/README.md @@ -0,0 +1,88 @@ +# MPS File Solver + +Read and solve LP/MILP problems from standard MPS files using cuOpt. + +## Problem Description + +MPS (Mathematical Programming System) is a standard file format for representing linear and mixed-integer programming problems. This model demonstrates how to: + +1. Load an MPS file using `Problem.readMPS()` (static method) +2. Solve the problem using cuOpt's GPU-accelerated solver +3. Extract and display the solution + +This is useful when you have optimization problems in standard MPS format from other solvers, modeling tools, or benchmark libraries like MIPLIB. + +## MPS File Format + +MPS is a column-oriented format with sections: + +``` +NAME problem_name +ROWS + N OBJ (objective row) + L CON1 (≤ constraint) + G CON2 (≥ constraint) + E CON3 (= constraint) +COLUMNS + X1 OBJ 1.0 + X1 CON1 2.0 + X2 OBJ 2.0 + X2 CON1 3.0 +RHS + RHS CON1 10.0 +BOUNDS + LO BND X1 0.0 + UP BND X1 5.0 +ENDATA +``` + +## Usage + +```bash +# Solve the sample problem +python model.py + +# Solve a custom MPS file +python model.py --file path/to/problem.mps + +# With time limit +python model.py --file problem.mps --time-limit 120 +``` + +## Model Characteristics + +- **Type**: LP or MILP (detected from MPS file) +- **Input**: Standard MPS file format +- **Output**: Solution values, objective, status + +## Sample Problem + +The included `data/air05.mps` is a MIPLIB benchmark (airline crew scheduling): + +- **Variables**: 7,195 (binary) +- **Constraints**: 426 +- **Known optimal**: 26,374 +- **Typical solve time**: ~2 seconds + +## Key API Usage + +```python +from cuopt.linear_programming.problem import Problem +from cuopt.linear_programming.solver_settings import SolverSettings + +# Load MPS file (static method - returns Problem object) +problem = Problem.readMPS("path/to/problem.mps") + +# Configure and solve +settings = SolverSettings() +settings.set_parameter("time_limit", 60) +problem.solve(settings) + +# Check solution +if problem.Status.name in ["Optimal", "FeasibleFound"]: + print(f"Objective: {problem.ObjValue}") +``` + +## Source + +Based on cuOpt's built-in MPS support via `Problem.readMPS()`. diff --git a/optional-skills/mlops/nvidia/cuopt-numerical-optimization-api-python/assets/mps_solver/model.py b/optional-skills/mlops/nvidia/cuopt-numerical-optimization-api-python/assets/mps_solver/model.py new file mode 100644 index 0000000000000..fb8918c11c2c5 --- /dev/null +++ b/optional-skills/mlops/nvidia/cuopt-numerical-optimization-api-python/assets/mps_solver/model.py @@ -0,0 +1,283 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 + +""" +MPS File Solver using cuOpt Python API + +Read and solve LP/MILP problems from standard MPS files using +cuOpt's built-in readMPS method. + +Default benchmark: air05.mps (airline crew scheduling from MIPLIB) +- Best known optimal: 26,374 +""" + +import os +import gzip +import urllib.request +from typing import Optional + +from cuopt.linear_programming.problem import Problem +from cuopt.linear_programming.solver_settings import SolverSettings + + +# MIPLIB benchmark URL +AIR05_URL = "https://miplib.zib.de/WebData/instances/air05.mps.gz" +AIR05_OPTIMAL = 26374 # Best known optimal solution + + +def download_air05(data_dir: str) -> str: + """Download air05.mps from MIPLIB if not present.""" + mps_file = os.path.join(data_dir, "air05.mps") + + if os.path.exists(mps_file): + return mps_file + + os.makedirs(data_dir, exist_ok=True) + gz_file = os.path.join(data_dir, "air05.mps.gz") + + print("Downloading air05.mps from MIPLIB...") + urllib.request.urlretrieve(AIR05_URL, gz_file) + + # Decompress + print("Decompressing...") + with gzip.open(gz_file, "rb") as f_in: + with open(mps_file, "wb") as f_out: + f_out.write(f_in.read()) + + # Clean up + os.remove(gz_file) + print(f"Downloaded: {mps_file}") + + return mps_file + + +def solve_mps( + filepath: str, + time_limit: float = 60.0, + mip_gap: float = 0.01, + verbose: bool = True, +) -> tuple: + """ + Solve an LP/MILP problem from an MPS file. + + Parameters + ---------- + filepath : str + Path to the MPS file + time_limit : float + Solver time limit in seconds + mip_gap : float + MIP relative gap tolerance + verbose : bool + Print solver output + + Returns + ------- + tuple + (problem, solution_dict) or (problem, None) if no solution + """ + + # Read MPS file directly (static method returns Problem object) + problem = Problem.readMPS(filepath) + + print(f"Loaded MPS file: {filepath}") + print(f"Variables: {problem.NumVariables}") + print(f"Constraints: {problem.NumConstraints}") + print(f"Is MIP: {problem.IsMIP}") + + # Solver settings + settings = SolverSettings() + settings.set_parameter("time_limit", time_limit) + settings.set_parameter("log_to_console", verbose) + settings.set_parameter("mip_relative_gap", mip_gap) + + # Solve + print("\nSolving...") + problem.solve(settings) + + # Extract solution + status = problem.Status.name + print(f"\nStatus: {status}") + + if status in ["Optimal", "FeasibleFound", "PrimalFeasible"]: + solution = { + "status": status, + "objective": problem.ObjValue, + "num_variables": problem.NumVariables, + "num_constraints": problem.NumConstraints, + "is_mip": problem.IsMIP, + "mip_gap": mip_gap, + } + + # Get variable values (use getVariables() for MPS-loaded problems) + var_values = {} + try: + variables = problem.getVariables() + for var in variables: + val = var.getValue() + if abs(val) > 1e-6: # Only include non-zero values + var_values[var.Name] = val + except (AttributeError, Exception): + # For MPS problems, variable access may be limited + pass + + solution["variables"] = var_values + return problem, solution + else: + return problem, None + + +def compare_gaps( + filepath: str, + time_limit: float = 120.0, + known_optimal: Optional[float] = None, +) -> dict: + """ + Compare solutions at different MIP gap tolerances. + + Parameters + ---------- + filepath : str + Path to the MPS file + time_limit : float + Solver time limit per run + known_optimal : float, optional + Known optimal objective value. If provided, results include + "gap_to_optimal" (percent above optimal). Omit for generic MPS files. + + Returns + ------- + dict + Results for each gap tolerance + """ + gaps = [0.01, 0.001] # 1% and 0.1% + results = {} + + for gap in gaps: + print(f"\n{'=' * 60}") + print(f"Solving with MIP gap = {gap * 100}%") + print(f"{'=' * 60}") + + problem, solution = solve_mps( + filepath=filepath, time_limit=time_limit, mip_gap=gap, verbose=True + ) + + if solution: + results[gap] = { + "objective": solution["objective"], + "status": solution["status"], + } + if known_optimal is not None: + results[gap]["gap_to_optimal"] = ( + (solution["objective"] - known_optimal) + / known_optimal + * 100 + ) + else: + results[gap] = {"objective": None, "status": "No solution"} + + return results + + +if __name__ == "__main__": + import argparse + + parser = argparse.ArgumentParser(description="Solve LP/MILP from MPS file") + parser.add_argument( + "--file", type=str, default=None, help="Path to MPS file" + ) + parser.add_argument( + "--time-limit", type=float, default=60.0, help="Solver time limit" + ) + parser.add_argument( + "--mip-gap", type=float, default=0.01, help="MIP gap tolerance" + ) + parser.add_argument( + "--compare", action="store_true", help="Compare 1%% vs 0.1%% gap" + ) + parser.add_argument( + "--known-optimal", + type=float, + default=None, + help="Known optimal objective value (enables gap-to-optimal reporting)", + ) + args = parser.parse_args() + + print("=" * 60) + print("MPS File Solver using cuOpt") + print("=" * 60) + + # Determine MPS file to use + script_dir = os.path.dirname(os.path.abspath(__file__)) + data_dir = os.path.join(script_dir, "data") + + if args.file: + mps_file = args.file + else: + # Download air05.mps if not present + mps_file = download_air05(data_dir) + + # Use known optimal only when explicitly set or when using default air05 + known_optimal = args.known_optimal + if known_optimal is None and mps_file.endswith("air05.mps"): + known_optimal = AIR05_OPTIMAL + + if args.compare: + # Compare different gap tolerances + print(f"\nComparing MIP gap tolerances on: {mps_file}") + if known_optimal is not None: + print(f"Best known optimal: {known_optimal}") + + results = compare_gaps( + mps_file, time_limit=args.time_limit, known_optimal=known_optimal + ) + + print() + print("=" * 60) + print("COMPARISON SUMMARY") + print("=" * 60) + if known_optimal is not None: + print(f"Best known optimal: {known_optimal}") + print() + header = f"{'Gap Tolerance':<15} {'Objective':<15}" + if known_optimal is not None: + header += f" {'Gap to Optimal':<15}" + print(header) + print("-" * (45 if known_optimal is None else 60)) + + for gap, result in sorted(results.items()): + if result["objective"] is not None: + line = f"{gap * 100:.1f}%{'':<12} {result['objective']:<15.0f}" + if known_optimal is not None: + line += f" {result['gap_to_optimal']:.2f}%" + print(line) + else: + print(f"{gap * 100:.1f}%{'':<12} {'No solution':<15}") + else: + # Single solve + print(f"\nMPS File: {mps_file}") + print(f"Time Limit: {args.time_limit}s") + print(f"MIP Gap: {args.mip_gap * 100}%") + print() + + problem, solution = solve_mps( + filepath=mps_file, + time_limit=args.time_limit, + mip_gap=args.mip_gap, + verbose=True, + ) + + if solution: + print() + print("=" * 60) + print("SOLUTION") + print("=" * 60) + print(f"Status: {solution['status']}") + print(f"Objective Value: {solution['objective']:.0f}") + if known_optimal is not None: + print(f"Best Known Optimal: {known_optimal}") + print( + f"Gap to Optimal: {(solution['objective'] - known_optimal) / known_optimal * 100:.2f}%" + ) + else: + print("\nNo feasible solution found.") diff --git a/optional-skills/mlops/nvidia/cuopt-numerical-optimization-api-python/assets/mps_solver/results.md b/optional-skills/mlops/nvidia/cuopt-numerical-optimization-api-python/assets/mps_solver/results.md new file mode 100644 index 0000000000000..4100dea6b2312 --- /dev/null +++ b/optional-skills/mlops/nvidia/cuopt-numerical-optimization-api-python/assets/mps_solver/results.md @@ -0,0 +1,90 @@ +# MPS Solver Results + +## Problem: air05.mps (MIPLIB benchmark) + +**Description:** Airline crew scheduling - set partitioning problem + +### Problem Characteristics +- **Variables:** 7195 (all binary) +- **Constraints:** 426 +- **Nonzeros:** 52121 +- **Best Known Optimal:** 26374 + +--- + +## Gap Tolerance Comparison + +Comparing different MIP relative gap tolerances to show trade-off between solution quality and solve time. + +### Run Configuration +- **Time Limit:** 60 seconds +- **cuOpt Version:** 26.2.0 +- **Device:** Quadro RTX 8000 (47.24 GiB VRAM) +- **CPU:** AMD Ryzen Threadripper PRO 3975WX (32 cores) + +### Results Summary + +| Gap Tolerance | Objective | Gap to Optimal | Solve Time | Nodes Explored | +|--------------|-----------|----------------|------------|----------------| +| 0.1% | **26374** | 0.00% | 8.42s | 386 | +| 1.0% | 26491 | 0.44% | 3.23s | 328 | + +### Key Observations + +1. **Tighter gap finds optimal**: The 0.1% gap tolerance found the exact best-known optimal solution (26374) +2. **Trade-off**: The looser 1.0% gap converged faster (3.2s vs 8.4s) but with 0.44% suboptimality +3. **Both are fast**: cuOpt solved this 7195-variable MILP in under 10 seconds + +--- + +## Detailed Solver Output (0.1% gap) + +``` +Solving a problem with 426 constraints, 7195 variables (7195 integers), and 52121 nonzeros + +Presolve removed: 90 constraints, 1116 variables, 16171 nonzeros +Presolved problem: 336 constraints, 6079 variables, 35950 nonzeros + +Root relaxation objective +2.58776093e+04 + +Strong branching using 7 threads and 222 fractional variables +Explored 386 nodes in 7.73s. + +Optimal solution found within relative MIP gap tolerance (1.0e-03) +Solution objective: 26374.000000 +relative_mip_gap 0.000992 +total_solve_time 8.421934 +``` + +--- + +## Detailed Solver Output (1.0% gap) + +``` +Solving a problem with 426 constraints, 7195 variables (7195 integers), and 52121 nonzeros + +Presolve removed: 90 constraints, 1116 variables, 16171 nonzeros +Presolved problem: 336 constraints, 6079 variables, 35950 nonzeros + +Root relaxation objective +2.58776093e+04 + +Strong branching using 63 threads and 222 fractional variables +Explored 328 nodes in 1.09s. + +Optimal solution found within relative MIP gap tolerance (1.0e-02) +Solution objective: 26491.000000 +relative_mip_gap 0.009669 +total_solve_time 3.233650 +``` + +--- + +## Usage + +```bash +# Default: download air05.mps and solve with comparison +python model.py --compare --time-limit 60 + +# Solve custom MPS file +python model.py --file path/to/problem.mps --time-limit 300 --mip-gap 0.001 +``` diff --git a/optional-skills/mlops/nvidia/cuopt-numerical-optimization-api-python/assets/portfolio/README.md b/optional-skills/mlops/nvidia/cuopt-numerical-optimization-api-python/assets/portfolio/README.md new file mode 100644 index 0000000000000..cf2173a455d72 --- /dev/null +++ b/optional-skills/mlops/nvidia/cuopt-numerical-optimization-api-python/assets/portfolio/README.md @@ -0,0 +1,7 @@ +# Portfolio optimization (QP) + +Minimize portfolio variance (risk) subject to fully invested (sum x = 1) and minimum return. Three assets; Q must be PSD. + +**Run:** `python model.py` + +**Note:** QP is beta; objective must be MINIMIZE. diff --git a/optional-skills/mlops/nvidia/cuopt-numerical-optimization-api-python/assets/portfolio/model.py b/optional-skills/mlops/nvidia/cuopt-numerical-optimization-api-python/assets/portfolio/model.py new file mode 100644 index 0000000000000..0196efdcf8b18 --- /dev/null +++ b/optional-skills/mlops/nvidia/cuopt-numerical-optimization-api-python/assets/portfolio/model.py @@ -0,0 +1,49 @@ +# SPDX-FileCopyrightText: Copyright (c) 2025-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 + +""" +Portfolio: minimize variance x'Qx subject to sum(x)=1, r'x >= target, x >= 0. +QP is beta; MUST use MINIMIZE. +""" + +from cuopt.linear_programming.problem import Problem, CONTINUOUS, MINIMIZE +from cuopt.linear_programming.solver_settings import SolverSettings + +problem = Problem("Portfolio") + +x1 = problem.addVariable(lb=0, ub=1, vtype=CONTINUOUS, name="stock_a") +x2 = problem.addVariable(lb=0, ub=1, vtype=CONTINUOUS, name="stock_b") +x3 = problem.addVariable(lb=0, ub=1, vtype=CONTINUOUS, name="stock_c") + +r1, r2, r3 = 0.12, 0.08, 0.05 +target_return = 0.08 + +problem.setObjective( + 0.04 * x1 * x1 + + 0.02 * x2 * x2 + + 0.01 * x3 * x3 + + 0.02 * x1 * x2 + + 0.01 * x1 * x3 + + 0.016 * x2 * x3, + sense=MINIMIZE, +) +problem.addConstraint(x1 + x2 + x3 == 1, name="budget") +problem.addConstraint( + r1 * x1 + r2 * x2 + r3 * x3 >= target_return, name="min_return" +) + +settings = SolverSettings() +settings.set_parameter("time_limit", 60) +problem.solve(settings) + +if problem.Status.name in ["Optimal", "PrimalFeasible"]: + print(f"Portfolio variance: {problem.ObjValue:.6f}") + print(f"Std dev: {problem.ObjValue**0.5:.4f}") + print(f" Stock A: {x1.getValue() * 100:.2f}%") + print(f" Stock B: {x2.getValue() * 100:.2f}%") + print(f" Stock C: {x3.getValue() * 100:.2f}%") + print( + f"Expected return: {(r1 * x1.getValue() + r2 * x2.getValue() + r3 * x3.getValue()) * 100:.2f}%" + ) +else: + print(f"Status: {problem.Status.name}") diff --git a/optional-skills/mlops/nvidia/cuopt-numerical-optimization-api-python/evals/SOURCES.md b/optional-skills/mlops/nvidia/cuopt-numerical-optimization-api-python/evals/SOURCES.md new file mode 100644 index 0000000000000..f258683e38153 --- /dev/null +++ b/optional-skills/mlops/nvidia/cuopt-numerical-optimization-api-python/evals/SOURCES.md @@ -0,0 +1,40 @@ +# Sources + +Eval prompts in `evals.json` for the `cuopt-numerical-optimization-api-python` skill are +adapted from the **OptiGuide / OptiMind IndustryOR** dataset: + +- Repository: [microsoft/OptiGuide](https://github.com/microsoft/OptiGuide) +- File: [`optimind/data/optimind_cleaned_classified_industryor.csv`](https://github.com/microsoft/OptiGuide/blob/main/optimind/data/optimind_cleaned_classified_industryor.csv) +- License: MIT (Copyright (c) Microsoft Corporation) + +Each entry's `source` field references the original row index. Problem +statements are quoted verbatim; ground-truth values are the dataset's +optimal objective values. + +## License + +The MIT license under which the source dataset is distributed: + +``` +MIT License + +Copyright (c) Microsoft Corporation. + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE +``` diff --git a/optional-skills/mlops/nvidia/cuopt-numerical-optimization-api-python/evals/evals.json b/optional-skills/mlops/nvidia/cuopt-numerical-optimization-api-python/evals/evals.json new file mode 100644 index 0000000000000..57ff74c67a7e5 --- /dev/null +++ b/optional-skills/mlops/nvidia/cuopt-numerical-optimization-api-python/evals/evals.json @@ -0,0 +1,1091 @@ +[ + { + "id": "lpmilp-001-production-planning-problem", + "question": "A factory produces two types of food, I and II, and currently has 50 skilled workers. It is known that one skilled worker can produce $10 \\ \\mathrm{kg} / \\ \\mathrm{h}$ of food I or $6 \\ \\mathrm{kg} / \\ \\mathrm{h}$ of food II. According to contract bookings, the weekly demand for these two foods will rise sharply, as shown in Table 1-11. Therefore, the factory has decided to train 50 new workers by the end of the 8th week. It is known that a worker works $40 \\ \\mathrm{h}$ per week, and a skilled worker can train up to three new workers in two weeks (during the training period, both the skilled worker and the trainees do not participate in production). The weekly wage of a skilled worker is 360 yuan, the weekly wage of a trainee during the training period is 120 yuan, and after training, the wage is 240 yuan per week, with the same production efficiency as skilled workers. During the transition period of training, many skilled workers are willing to work overtime, and the factory has decided to arrange some workers to work $60 \\ \\mathrm{h}$ per week, with a weekly wage of 540 yuan. If the booked food cannot be delivered on time, the compensation fee for each week of delay per $ \\ \\mathrm{kg}$ is 0.5 yuan for food I and 0.6 yuan for food II. Under these conditions, how should the factory make comprehensive arrangements to minimize the total cost?\n\nTable 1-11\n\n| Week | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 |\n|------|---|---|---|---|---|---|---|---|\n| I | 10000 | 10000 | 12000 | 12000 | 16000 | 16000 | 20000 | 20000 |\n| II | 6000 | 7200 | 8400 | 10800 | 10800 | 12000 | 12000 | 12000 |", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "219816.0", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 0 (MIT)" + }, + { + "id": "lpmilp-002-capacitated-lot-sizing-problem-c", + "question": "Each year $t=1,\\dots ,n$ two production lines deliver $a_1=10$ and $a_2=15$ new fighter jets (25 total). $n=10$. Decide how many of that year's 25 aircraft, $x_t$, enter combat immediately and how many, $y_t=25-x_t$, become training platforms. A training jet produces five newly qualified pilots who are available at the start of the next year; every combat jet must be matched with one trained pilot to be operational, and training jets can be reassigned to combat in later years. Starting with no aircraft or pilots, choose integer sequences $\\{x_t,y_t\\}_{t=1}^n$ to maximise the cumulative number of operational combat jet-years $\\sum_{t=1}^{n} x_t$, subject to annual pilot-availability and fleet-balance constraints.", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "1350.0", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 1 (MIT)" + }, + { + "id": "lpmilp-003-capacitated-lot-sizing-problem-c", + "question": "A company specializing in foldable tables needs to create an optimal production and human resources plan for a six-month period (January to June) to maximize its total net profit. The plan must detail monthly in-house production levels, outsourcing quantities, and workforce management (hiring/firing).\n\n**Initial Conditions (at the start of January):**\n- Initial Workforce: 1,000 employees\n- Initial Inventory: 15,000 units\n\n**Revenue and Cost Structure:**\n- **Sales Price:** 300 Yuan per unit sold.\n- **Raw Material Cost:** 90 Yuan per unit, applicable *only* to units produced in-house.\n- **Outsourcing Cost:** 200 Yuan per unit for finished tables acquired from a third-party supplier. This is an all-inclusive cost.\n- **Inventory Holding Cost:** 15 Yuan per unit for any inventory held at the end of a month.\n- **Backorder Cost:** 35 Yuan per unit for any unfulfilled demand (stockout) carried over to the next month.\n\n**Labor and Production Parameters:**\n- **Labor Requirement:** Each in-house unit requires 5 labor hours to produce.\n- **Regular Labor:** Each worker provides 160 regular working hours per month (8 hours/day * 20 days/month). The company pays a regular wage of 30 Yuan/hour for these 160 hours, regardless of full utilization.\n- **Overtime Labor:** Workers can perform overtime. Total overtime hours per month for the entire workforce cannot exceed 20 hours per worker. The overtime wage is 40 Yuan/hour.\n- **Workforce Management:** The company can hire or fire workers each month. The cost to hire a new worker is 5,000 Yuan, and the cost to fire a worker is 8,000 Yuan.\n\n**Demand and Fulfillment Logic:**\n- Unfulfilled demand from one month is back-ordered and must be met in subsequent months.\n- The company fulfills orders (both current demand and backorders) using available inventory from the previous month, current in-house production, and outsourced units.\n\n**Terminal Condition (at the end of June):**\n- The ending inventory must be at least 10,000 units.\n- All backorders must be cleared (i.e., ending backorders must be zero).\n\n**Forecasted Demand:**\n| Month | January | February | March | April | May | June |\n|:---:|:---:|:---:|:---:|:---:|:---:|:---:|\n| Demand Forecast | 20,000 | 40,000 | 42,000 | 35,000 | 19,000 | 18,500 |\n\nBased on this information, formulate the optimal six-month operational plan.", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "10349920.0", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 2 (MIT)" + }, + { + "id": "lpmilp-004-farm-planning", + "question": "A farmer needs to decide how many cows, sheep, and chickens to raise in order to achieve maximum profit. The farmer can sell cows, sheep, and chickens for $500, $200, and $8 each, respectively. The feed costs for each cow, sheep, and chicken are $100, $80, and $5, respectively. The profit is the difference between the selling price and the feed cost. Each cow, sheep, and chicken produces 10, 5, and 3 units of manure per day, respectively. Due to the limited time the farm staff has for cleaning the farm each day, they can handle up to 800 units of manure. Additionally, because of the limited farm size, the farmer can raise at most 50 chickens. Furthermore, the farmer must have at least 10 cows to meet customer demand. The farmer must also raise at least 20 sheep. Finally, the total number of animals cannot exceed 100.", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "30400.0", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 3 (MIT)" + }, + { + "id": "lpmilp-005-diet-problem", + "question": "Mary is planning her dinner tonight. Every 100 grams of okra contains 3.2 grams of fiber, every 100 grams of carrots contains 2.7 grams of fiber, every 100 grams of celery contains 1.6 grams of fiber, and every 100 grams of cabbage contains 2 grams of fiber. How many grams of each type of food should Mary buy to maximize her fiber intake?\n\nShe is considering choosing one among salmon, beef, and pork as a protein source. For the chosen protein she must take at least one gram of it.\n\nShe also considers choosing at least two kinds of vegetables among okra, carrots, celery, and cabbage. For each of the selected vegetables, she must take at least one gram.\n\nThe price of salmon is $4 per 100 grams, beef is $3.6 per 100 grams, pork is $1.8 per 100 grams. The price of okra is $2.6 per 100 grams, carrots are $1.2 per 100 grams, celery is $1.6 per 100 grams, and cabbage is $2.3 per 100 grams. Mary has a budget of $15 for this meal.\n\nThe total food intake should be 600 grams.", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "18.95657143", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 4 (MIT)" + }, + { + "id": "lpmilp-006-capacitated-lot-sizing-problem-c", + "question": "The contract reservations for the next year for products I, II, and III of a certain factory in each quarter are shown in Table 1-10.\n\nTable 1-10\n| Product | 1 | 2 | 3 | 4 |\n|---------|------|------|------|------|\n| I | 1500 | 1000 | 2000 | 1200 |\n| II | 1500 | 1500 | 1200 | 1500 |\n| III | 1000 | 2000 | 1500 | 2500 |\n\nAt the beginning of the first quarter, there is no inventory for these three products, and it is required to have 150 units in stock for each product by the end of the fourth quarter. It is known that the factory has 15,000 production hours per quarter, and each unit of products I, II, and III requires 2, 4, and 3 hours respectively. Due to a change in equipment, product I cannot be produced in the second quarter. It is stipulated that if the products cannot be delivered on time, a compensation of 20 yuan per unit per quarter delay is required for products I and II, while for product III, the compensation is 10 yuan. Additionally, for products produced but not delivered in the current quarter, the inventory cost is 5 yuan per unit per quarter. How should the factory schedule production to minimize the total cost of compensation and inventory?", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "10755.0", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 5 (MIT)" + }, + { + "id": "lpmilp-007-transportation-problem", + "question": "An Italian transportation company needs to move some empty containers from its 6 warehouses (located in Verona, Perugia, Rome, Pescara, Taranto, and Lamezia) to major national ports (Genoa, Venice, Ancona, Naples, Bari). The container inventory at the warehouses is as follows:\n\n| | Empty Containers |\n|:---:|:---:|\n| Verona | 10 |\n| Perugia | 12 |\n| Rome | 20 |\n| Pescara | 24 |\n| Taranto | 18 |\n| Lamezia | 40 |\n\nThe demand at the ports is as follows:\n\n| | Container Demand |\n|:---:|:---:|\n| Genoa | 20 |\n| Venice | 15 |\n| Ancona | 25 |\n| Naples | 33 |\n| Bari | 21 |\n\nThe transport is carried out by a fleet of trucks. The cost to transport each container is proportional to the distance traveled by the trucks, with a rate of 30 euros per kilometer. Each truck can carry up to 2 containers. The distances are as follows:\n\n| | Genoa | Venice | Ancona | Naples | Bari |\n|:---:|:---:|:---:|:---:|:---:|:---:|\n| Verona | $290 \\mathrm{~km}$ | $115 \\mathrm{~km}$ | $355 \\mathrm{~km}$ | $715 \\mathrm{~km}$ | $810 \\mathrm{~km}$ |\n| Perugia | $380 \\mathrm{~km}$ | $340 \\mathrm{~km}$ | $165 \\mathrm{~km}$ | $380 \\mathrm{~km}$ | $610 \\mathrm{~km}$ |\n| Rome | $505 \\mathrm{~km}$ | $530 \\mathrm{~km}$ | $285 \\mathrm{~km}$ | $220 \\mathrm{~km}$ | $450 \\mathrm{~km}$ |\n| Pescara | $655 \\mathrm{~km}$ | $450 \\mathrm{~km}$ | $155 \\mathrm{~km}$ | $240 \\mathrm{~km}$ | $315 \\mathrm{~km}$ |\n| Taranto | $1010 \\mathrm{~km}$ | $840 \\mathrm{~km}$ | $550 \\mathrm{~km}$ | $305 \\mathrm{~km}$ | $95 \\mathrm{~km}$ |\n| Lamezia | $1072 \\mathrm{~km}$ | $1097 \\mathrm{~km}$ | $747 \\mathrm{~km}$ | $372 \\mathrm{~km}$ | $333 \\mathrm{~km}$ |\n\nWrite a mathematical program to find the minimum cost transportation policy and solve it.", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "904590.0", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 6 (MIT)" + }, + { + "id": "lpmilp-008-assignment-problem", + "question": "Now, we need to determine 4 out of 5 workers to complete one of the four tasks respectively. Due to each worker's different technical specialties, the time required for them to complete each task varies. The hours required by each worker to complete each task are shown in Table 5-2.\n\nTable 5-2\n| Worker | $A$ | $B$ | $C$ | $D$ |\n|--------|-----|-----|-----|-----|\n| I | 9 | 4 | 3 | 7 |\n| II | 4 | 6 | 5 | 6 |\n| III | 5 | 4 | 7 | 5 |\n| IV | 7 | 5 | 2 | 3 |\n| V | 10 | 6 | 7 | 4 |\n\nTry to find a job assignment plan that minimizes the total working hours.", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "14.0", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 7 (MIT)" + }, + { + "id": "lpmilp-009-profit-maximization-problem", + "question": "Haus Toys can manufacture and sell toy trucks, toy airplanes, toy boats, and toy trains. The profit for each truck sold is $5, each airplane $10, each boat $8, and each train $7. How many types of toys should Haus Toys manufacture to maximize profits?\n\nThere are 890 units of wood available. Each truck requires 12 units, each airplane 20 units, each boat 15 units, and each train 10 units.\n\nThere are 500 units of steel available. Each airplane requires 3 units, each boat 5 units, each train 4 units, and each truck 6 units.\n\nIf Haus Toys manufactures trucks, they will not manufacture trains.\n\nHowever, if they manufacture boats, they will also manufacture airplanes.\n\nThe number of toy boats manufactured cannot exceed the number of toy trains manufactured.", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "623.0", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 8 (MIT)" + }, + { + "id": "lpmilp-010-set-cover", + "question": "A convenience supermarket is planning to open several chain stores in a newly built residential area in the northwest suburb of the city. For shopping convenience, the distance from any residential area to one of the chain stores should not exceed $800 \\mathrm{~m}$. Table 5-1 shows the new residential areas and the residential areas within a radius of $800 \\mathrm{~m}$ from each of them. Question: What is the minimum number of chain stores the supermarket needs to build among the mentioned residential areas, and in which residential areas should they be built?\n\n| Area Code | Residential Areas within $800 \\mathrm{~m}$ Radius |\n|-----------|---------------------------------------------------|\n| A | A, C, E, G, H, I |\n| B | B, H, I |\n| C | A, C, G, H, I |\n| D | D, J |\n| E | A, E, G |\n| F | F, J, K |\n| G | A, C, E, G |\n| H | A, B, C, H, I |\n| I | A, B, C, H, I |\n| J | D, F, J, K, L |\n| K | F, J, K, L |\n| L | J, K, L |", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "3.0", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 9 (MIT)" + }, + { + "id": "lpmilp-011-production-planning-problem", + "question": "A company produces two types of small motorcycles, where type A is entirely manufactured by the company, and type B is assembled from imported parts. The production, assembly, and inspection time required for each unit of these two products are shown in Table 3.2.\n\nTable 3.2\n\n| Type | Process | | | Selling Price
(Yuan/unit) |\n| :---: | :---: | :---: | :---: | :---: |\n| | Manufacturing | Assembly | Inspection | |\n| Type A (hours/unit) | 20 | 5 | 3 | 650 |\n| Type B (hours/unit) | 0 | 7 | 6 | 725 |\n| Max production capacity per week (hours) | 120 | 80 | 40 | |\n| Production cost per hour (Yuan) | 12 | 8 | 10 | |\n\nIf the company's operational goals and targets are as follows:\n\n$p_{1}$ : The total profit per week should be at least 3000 yuan;\n\n$p_{2}$ : At least 5 units of type A motorcycles should be produced per week;\n\n$p_{3}$ : Minimize the idle time of each process as much as possible. The weight coefficients of the three processes are their hourly costs, and overtime is not allowed.\n\nTry to establish a model for this problem.", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "272.0", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 10 (MIT)" + }, + { + "id": "lpmilp-012-facility-location-problem", + "question": "Red Star Plastics Factory produces six distinct types of plastic containers. Each container type is characterized by a specific volume, market demand, and unit variable production cost, as detailed in Table 5-11.\n\n**Table 5-11: Container Data**\n| Container Type (Code) | 1 | 2 | 3 | 4 | 5 | 6 |\n| :------------------------------ | :--- | :--- | :--- | :--- | :--- | :---- |\n| Volume ($\\text{cm}^3$) | 1500 | 2500 | 4000 | 6000 | 9000 | 12000 |\n| Market Demand (units) | 500 | 550 | 700 | 900 | 400 | 300 |\n| Unit Variable Production Cost (Yuan/unit) | 5 | 8 | 10 | 12 | 16 | 18 |\n\nThe production of any container type necessitates the use of its dedicated specialized equipment. If the decision is made to **activate** the production equipment for a particular container type (i.e., if the production quantity of that type is greater than zero), a fixed setup cost of 1200 Yuan is incurred for that specific equipment.\n\nShould the production quantity of a certain container type be insufficient to meet its direct demand, the factory has the option to utilize other container types with **larger or equal volume** as substitutes to fulfill this unmet demand. For instance, type 2 containers (volume 2500 $\\text{cm}^3$) can be used to satisfy the demand for type 1 containers (requiring a volume of 1500 $\\text{cm}^3$), but type 1 containers cannot be used for type 2 demand. In this problem, the container type codes are pre-sorted in ascending order of their volumes.\n\n**Question:**\nHow should the factory organize its production? The objective is to develop a production plan that minimizes the total cost—comprising the sum of variable production costs for all containers produced and the fixed costs for all activated equipment—while ensuring that the demand for all container types is fully met.", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "43200.0", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 11 (MIT)" + }, + { + "id": "lpmilp-013-profit-maximization-problem", + "question": "Tom and Jerry just bought a farm in Sunshine Valley, and they are considering using it to plant corn, wheat, soybeans, and sorghum. The profit per acre for planting corn is $1500, the profit per acre for planting wheat is $1200, the profit per acre for planting soybeans is $1800, and the profit per acre for planting sorghum is $1600. To maximize their profit, how many acres of land should they allocate to each crop? Tom and Jerry’s farm has a total area of 100 acres.\n\nThe land area used for planting corn must be at least twice the land area used for planting wheat.\n\nThe land area used for planting soybeans must be at least half the land area used for planting sorghum.\n\nThe land area used for planting wheat must be three times the land area used for planting sorghum.", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "180000.0", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 12 (MIT)" + }, + { + "id": "lpmilp-014-knapsack", + "question": "Mary is planning tonight's dinner. She wants to choose a combination of protein and vegetables to maximize her protein intake for the meal. Her protein options are chicken, salmon, and tofu, which can be bought in any quantity.\n\n- Chicken: 23g protein, $3.00 cost, per 100g.\n- Salmon: 20g protein, $5.00 cost, per 100g.\n- Tofu: 8g protein, $1.50 cost, per 100g.\n\nShe also wants to choose from a list of five vegetables, sold in 100g packs. She must select at least three different types of vegetables.\n\n- Broccoli (100g pack): 2.8g protein, $1.20 cost.\n- Carrots (100g pack): 0.9g protein, $0.80 cost.\n- Spinach (100g pack): 2.9g protein, $1.50 cost.\n- Bell Pepper (100g pack): 1.0g protein, $1.00 cost.\n- Mushrooms (100g pack): 3.1g protein, $2.00 cost.\n\nMary has two main constraints:\n1. Her total budget is $20.\n2. The total weight of all food must not exceed 800 grams.\n\nHow should Mary choose her ingredients to get the maximum possible amount of protein?", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "123.8", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 13 (MIT)" + }, + { + "id": "lpmilp-015-lot-sizing-problem", + "question": "A certain factory needs to use a special tool over $n$ planning stages. At stage $j$, $r_j$ specialized tools are needed. At the end of this stage, all tools used within this stage must be sent for repair before they can be reused. There are two repair methods: one is slow repair, which is cheaper (costs $b$ per tool) but takes longer ($p$ stages to return, e.g. if a tool goes to repair after stage 1, it will return at stage 1+p); the other is fast repair, which costs $c$ per tool $(c > b)$ and is faster, requiring only $q$ stages to return $(q < p)$. If the repaired tools cannot meet the needs, new ones must be purchased, with a cost of $a$ per new tool $(a > c)$. This special tool will no longer be used after $n$ stages. Determine an optimal plan for purchasing and repairing the tools to minimize the cost spent on tools during the planning period.\\n\\nn = 10 # number of stages\\nr = [3, 5, 2, 4, 6, 5, 4, 3, 2, 1] # tool requirements per stage, indexing starts at 1\\na = 10 # cost of buying a new tool\\nb = 1 # cost of slow repair\\nc = 3 # cost of fast repair\\np = 3 # slow repair duration\\nq = 1 # fast repair duration", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "134.0", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 14 (MIT)" + }, + { + "id": "lpmilp-016-lot-sizing-problem", + "question": "A store plans to formulate the purchasing and sales plan for a certain product for the first quarter of next year. It is known that the warehouse capacity of the store can store up to 500 units of the product, and there are 200 units in stock at the end of this year. The store purchases goods once at the beginning of each month. The purchasing and selling prices of the product in each month are shown in Table 1.3.\n\nTable 1.3\n\n| Month | 1 | 2 | 3 |\n| :---: | :---: | :---: | :---: |\n| Purchasing Price (Yuan) | 8 | 6 | 9 |\n| Selling Price (Yuan) | 9 | 8 | 10 |\n\nNow, determine how many units should be purchased and sold each month to maximize the total profit, and express this problem as a linear programming model.", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "4100.0", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 15 (MIT)" + }, + { + "id": "lpmilp-017-production-planning-problem", + "question": "A textile factory produces two types of fabrics: one for clothing and the other for curtains. The factory operates two shifts, with a weekly production time set at 110 hours. Both types of fabrics are produced at a rate of 1000 meters per hour. Assuming that up to 70,000 meters of curtain fabric can be sold per week, with a profit of 2.5 yuan per meter, and up to 45,000 meters of clothing fabric can be sold per week, with a profit of 1.5 yuan per meter, the factory has the following objectives in formulating its production plan:\n\n$p_{1}$ : The weekly production time must fully utilize 110 hours;\n\n$p_{2}$ : Overtime should not exceed 10 hours per week;\n\n$p_{3}$ : At least 70,000 meters of curtain fabric and 45,000 meters of clothing fabric must be sold per week;\n\n$p_{4}$ : Minimize overtime as much as possible.\n\nFormulate a model for this problem.", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "5.0", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 16 (MIT)" + }, + { + "id": "lpmilp-018-production-planning-problem", + "question": "A furniture store can choose to order chairs from three different manufacturers: A, B, and C. The cost of ordering each chair from manufacturer A is $50, from manufacturer B is $45, and from manufacturer C is $40. The store needs to minimize the total cost of the order.\n\nAdditionally, each order from manufacturer A will include 15 chairs, while each order from manufacturers B and C will include 10 chairs. The number of orders must be an integer. The store needs to order at least 100 chairs.\n\nEach order from manufacturer A will include 15 chairs, while each order from manufacturers B and C will include 10 chairs. The store needs to order at most 500 chairs.\n\nIf the store decides to order chairs from manufacturer A, it must also order at least 10 chairs from manufacturer B.\n\nFurthermore, if the store decides to order chairs from manufacturer B, it must also order chairs from manufacturer C.", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "4000.0", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 17 (MIT)" + }, + { + "id": "lpmilp-019-production-planning-problem", + "question": "Bright Future Toys wants to build and sell robots, model cars, building blocks, and dolls. The profit for each robot sold is $15, for each model car sold is $8, for each set of building blocks sold is $12, and for each doll sold is $5. How many types of toys should Bright Future Toys manufacture to maximize profit?\nThere are 1200 units of plastic available. Each robot requires 30 units of plastic, each model car requires 10 units of plastic, each set of building blocks requires 20 units of plastic, and each doll requires 15 units of plastic.\n\nThere are 800 units of electronic components available. Each robot requires 8 units of electronic components, each model car requires 5 units of electronic components, each set of building blocks requires 3 units of electronic components, and each doll requires 2 units of electronic components.\n\nIf Bright Future Toys manufactures robots, they will not manufacture dolls.\n\nHowever, if they manufacture model cars, they will also manufacture building blocks.\n\nThe number of dolls manufactured cannot exceed the number of model cars manufactured.", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "956.0", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 18 (MIT)" + }, + { + "id": "lpmilp-020-lot-sizing-problem", + "question": "A restaurant needs to order dining tables from three different suppliers, A, B, and C. The cost of ordering each dining table from Supplier A is $120, from Supplier B is $110, and from Supplier C is $100. The restaurant needs to minimize the total cost of the order.\n\nAdditionally, each order from Supplier A will include 20 tables, while each order from Suppliers B and C will include 15 tables. The number of orders must be an integer. The restaurant needs to order at least 150 tables.\n\nEach order from Supplier A will include 20 tables, and each order from Suppliers B and C will include 15 tables. The restaurant needs to order no more than 600 tables.\n\nIf the restaurant decides to order tables from Supplier A, it must also order at least 30 tables from Supplier B.\n\nAdditionally, if the restaurant decides to order tables from Supplier B, it must also order tables from Supplier C.", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "15000.0", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 19 (MIT)" + }, + { + "id": "lpmilp-021-production-planning-problem", + "question": "A company plans to produce 3 types of products $A_{1}, A_{2}, A_{3}$. It can produce for 22 days in a month. The following table gives the maximum demand (unit $=100 \\mathrm{~kg}$), price ($\\$ / 100 \\mathrm{Kg}$), production cost (per 100Kg product), and production quota (the maximum number of 100kg units that can be produced in one day if all production lines are devoted to this product).\n\n| Product | $A_{1}$ | $A_{2}$ | $A_{3}$ |\n| :---: | :---: | :---: | :---: |\n| Maximum Demand | 5300 | 4500 | 5400 |\n| Selling Price | $124$ | $109$ | $115$ |\n| Production Cost | $73.30$ | $52.90$ | $65.40$ |\n| Production Quota | 500 | 450 | 550 |\n\nThe fixed activation cost of the production line is as follows:\n\n| Product | $A_{1}$ | $A_{2}$ | $A_{3}$ |\n| :---: | :---: | :---: | :---: |\n| Activation Cost | $170000$ | $150000$ | $100000$ |\n\nMinimum production batch:\n\n$$\n\\begin{array}{c|ccc}\nProduct & A_{1} & A_{2} & A_{3} \\\\\n\\hline\nMinimum Batch & 20 & 20 & 16\n\\end{array}\n$$\n\nPlease formulate an operations research model to determine a production plan that maximizes total revenue while accommodating fixed activation costs and minimum production batch constraints.", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "270290.0", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 20 (MIT)" + }, + { + "id": "lpmilp-022-profit-maximization-problem", + "question": "Hongdou Clothing Factory uses three special equipment to produce shirts, short-sleeved shirts, and casual clothes respectively. It is known that the labor, material usage, selling price, and variable cost of each of the above products are as shown in Table 5-10.\n\nTable 5-10\n\n| Product Name | Labor per unit | Material per unit | Selling Price | Variable Cost |\n|--------------|----------------|------------------|---------------|---------------|\n| Shirt | 3 | 4 | 120 | 60 |\n| Short-sleeve | 2 | 3 | 80 | 40 |\n| Casual Cloth | 6 | 6 | 180 | 80 |\n\nIt is known that the available labor per week is 1500 units, the available material is 1600 units, and the weekly fixed costs for the three special equipment for producing shirts, short-sleeved shirts, and casual clothes are 2000, 1500, and 1000 respectively. Design a weekly production plan for the factory to maximize its profit.", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "24000.0", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 21 (MIT)" + }, + { + "id": "lpmilp-023-transportation-problem", + "question": "A manufacturing company needs to transport 1800 units of product from the warehouse to three different sales points. The company has four transportation options to choose from: truck, van, motorcycle, and electric vehicle. Since the van and electric vehicle both consume a lot of energy, the company wants to choose only one of these two options. Each trip with a truck generates 100 units of pollution, a van generates 50 units of pollution, a motorcycle generates 10 units of pollution, and an electric vehicle generates 0 units of pollution. The total pollution generated from all trips cannot exceed 2000 units. At least 10 trips must use a truck. Trucks, vans, motorcycles, and electric vehicles can transport 100 units, 80 units, 40 units, and 60 units of product per trip, respectively. The company needs to ensure that the total amount of transported product is at least 1800 units. Return the minimized pollution in units while meeting all constraints.", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "1000.0", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 22 (MIT)" + }, + { + "id": "lpmilp-024-portfoliooptimization", + "question": "An investor plans to invest 100,000 yuan, with two investment options to choose from. The first investment guarantees a return of 0.7 yuan for every 1 yuan invested after one year. The second investment guarantees a return of 2 yuan for every 1 yuan invested after two years, but the investment time must be in multiples of two years. In order to maximize the investor's earnings by the end of the third year, how should the investments be made? Formulate this as a linear programming problem.", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "510000.0", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 23 (MIT)" + }, + { + "id": "lpmilp-025-set-multi-cover", + "question": "The number of salespeople required at a 24-hour convenience store in different time periods is as follows: 2:00-6:00 - 10 people, 6:00-10:00 - 15 people, 10:00-14:00 - 25 people, 14:00-18:00 - 20 people, 18:00-22:00 - 18 people, 22:00-2:00 - 12 people. Salespeople start their shifts at 2:00, 6:00, 10:00, 14:00, 18:00, and 22:00, working continuously for 8 hours. Determine the minimum number of salespeople needed to meet the requirements.", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "53.0", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 24 (MIT)" + }, + { + "id": "lpmilp-026-factory-planning-problem", + "question": "A factory produces three types of products: I, II, and III. Each product needs to go through two processing procedures, A and B. The factory has two pieces of equipment that can complete process A, denoted as A1 and A2; it has three pieces of equipment that complete process B, denoted as B1, B2, and B3. Product I can be processed on any equipment for A and B; Product II can be processed on any A equipment but only on B1 for process B; Product III can only be processed on A2 and B2. Given the unit processing time on various machines, raw material costs, product sale prices, effective machine hours, and the costs of operating the machines at full capacity as shown in Table 1-4, the task is to arrange the optimal production plan to maximize the factory's profit.\n\nTable 1-4\n| Equipment | Product I | Product II | Product III | Effective Machine Hours | Operating Costs at Full Capacity (Yuan) |\n|------------|-----------|------------|-------------|--------------------------|------------------------------------------|\n| A1 | 5 | 10 | | 6000 | 300 |\n| A2 | 7 | 9 | 12 | 10000 | 321 |\n| B1 | 6 | 8 | | 4000 | 250 |\n| B2 | 4 | | 11 | 7000 | 783 |\n| B3 | 7 | | | 4000 | 200 |\n| Raw Material Cost (Yuan/Unit) | 0.25 | 0.35 | 0.50 | | |\n| Unit Price (Yuan/Unit) | 1.25 | 2.00 | 2.80 | | |", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "1146.4142", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 25 (MIT)" + }, + { + "id": "lpmilp-027-profit-maximization-problem", + "question": "Someone has a fund of 300,000 yuan and has the following investment projects in the next three years:\n(1) Investment can be made at the beginning of each year within three years, with an annual profit of 20% of the investment amount, and the principal and interest can be used for investment in the following year;\n(2) Investment is only allowed at the beginning of the first year, and it can be recovered at the end of the second year, with the total principal and interest amounting to 150% of the investment amount, but the investment limit is no more than 150,000 yuan;\n(3) Investment is allowed at the beginning of the second year within three years, and it can be recovered at the end of the third year, with the total principal and interest amounting to 160% of the investment amount, and the investment limit is 200,000 yuan;\n(4) Investment is allowed at the beginning of the third year within three years, and it can be recovered in one year with a profit of 40%, and the investment limit is 100,000 yuan.\nChapter One: Linear Programming and Simplex Method\nTry to determine an investment plan for this person that maximizes the principal and interest at the end of the third year.", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "580000.0", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 26 (MIT)" + }, + { + "id": "lpmilp-028-assignment-problem", + "question": "Jieli Company needs to recruit three types of professionals to work in the two regional branches located in Donghai City and Nanjiang City. The demand for different professionals in these regional branches is shown in Table 4-3. After assessing the situation of the applicants, the company has categorized them into 6 types. Table 4-4 lists the specialties each type of person can handle, the specialty they prefer, and the city they prefer to work in. The company's personnel arrangement considers the following three priorities:\n$p_1$: All three types of professionals needed are fully met;\n$p_2$: 4000 recruited personnel meet their preferred specialty;\n$p_3$: 4000 recruited personnel meet their preferred city.\nFormulate a plan to minimize the total number of people that need to move from one city to another to meet these priorities. Return the minimized objective value.\n\nTable 4-3\n| Branch Location | Specialty | Demand |\n|-----------------|-----------|--------|\n| Donghai City | 1 | 1000 |\n| Donghai City | 2 | 2000 |\n| Donghai City | 3 | 1500 |\n| Nanjiang City | 1 | 2000 |\n| Nanjiang City | 2 | 1000 |\n| Nanjiang City | 3 | 1000 |\n\nTable 4-4\n\n| Type | Number of People | Suitable Specialty | Preferred Specialty | Preferred City |\n|------|------------------|--------------------|---------------------|----------------|\n| 1 | 1500 | 1,2 | 1 | Donghai |\n| 2 | 1500 | 2,3 | 2 | Donghai |\n| 3 | 1500 | 1,3 | 1 | Nanjiang |\n| 4 | 1500 | 1,3 | 3 | Nanjiang |\n| 5 | 1500 | 2,3 | 3 | Donghai |\n| 6 | 1500 | 3 | 3 | Nanjiang |", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "2000.0", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 27 (MIT)" + }, + { + "id": "lpmilp-029-diet-problem", + "question": "Suppose a certain animal needs at least $700 \\mathrm{~g}$ of protein, $30 \\mathrm{~g}$ of minerals, and $100 \\mathrm{mg}$ of vitamins daily. There are 5 types of feed available, and the nutritional content and price per kilogram of each type of feed are shown in Table 1-5:\nTry to formulate a linear programming model that meets the animal's growth needs while minimizing the cost of selecting the feed.\nTable 1-6\n| Feed | Protein (g) | Minerals (g) | Vitamins (mg) | Price (¥/kg) | Feed | Protein (g) | Minerals (g) | Vitamins (mg) | Price (¥/kg) |\n|------|-------------|--------------|---------------|--------------|------|-------------|--------------|---------------|--------------|\n| 1 | 3 | 1 | 0.5 | 0.2 | 4 | 6 | 2 | 2 | 0.3 |\n| 2 | 2 | 0.5 | 1 | 0.7 | 5 | 18 | 0.5 | 0.8 | 0.8 |\n| 3 | 1 | 0.2 | 0.2 | 0.4 | | | | | |", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "32.43589744", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 28 (MIT)" + }, + { + "id": "lpmilp-030-factory-planning-problem", + "question": "A factory produces three types of products: I, II, and III. Each product must undergo two processing stages, A and B. The factory has two types of equipment to complete stage A (A1, A2) and three types of equipment to complete stage B (B1, B2, B3).\n\nThe production rules are as follows:\n- Product I can be processed on any type of A equipment (A1 or A2) and any type of B equipment (B1, B2, or B3).\n- Product II can be processed on any type of A equipment (A1 or A2), but for stage B, it can only be processed on B1 equipment.\n- Product III can only be processed on A2 equipment for stage A and B2 equipment for stage B.\n\nThe detailed data for processing time per piece, costs, sales price, and machine availability is provided in the table below. The objective is to determine the optimal production plan to maximize the factory's total profit.\n\nData Table\n| Equipment | Product I | Product II | Product III | Effective Machine Hours | Full - load Equipment Cost (Yuan) | Processing Cost per Machine Hour (Yuan/hour) |\n| :--- | :--- | :--- | :--- | :--- | :--- | :--- |\n| A1 | 5 | 10 | - | 6000 | 300 | 0.05 |\n| A2 | 7 | 9 | 12 | 10000 | 321 | 0.03 |\n| B1 | 6 | 8 | - | 4000 | 250 | 0.06 |\n| B2 | 4 | - | 11 | 7000 | 783 | 0.11 |\n| B3 | 7 | - | - | 4000 | 200 | 0.05 |\n| Raw Material Cost (Yuan/piece) | 0.25 | 0.35 | 0.5 | - | - | - |\n| Unit Price (Yuan/piece) | 1.25 | 2 | 2.8 | - | - | - |", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "1190.38", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 29 (MIT)" + }, + { + "id": "lpmilp-031-production-planning-problem", + "question": "A product consists of three components produced by four workshops, each with a limited number of production hours. Table 1.4 below provides the production rates of the three components. The objective is to determine the number of hours each workshop should allocate to each component to maximize the number of completed products. Formulate this problem.\n\nTable 1.4\n\n| Workshop | Production Capacity (hours) | Production Rate (units/hour) | | |\n| :------: | :-------------------------: | :--------------------------: | - | - |\n| | | Component 1 | Component 2 | Component 3 |\n| A | 100 | 10 | 15 | 5 |\n| B | 150 | 15 | 10 | 5 |\n| C | 80 | 20 | 5 | 10 |\n| D | 200 | 10 | 15 | 20 |", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "2924.0", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 30 (MIT)" + }, + { + "id": "lpmilp-032-knapsack", + "question": "A wealthy noble passed away, leaving the following inheritance:\n\n- A painting by Caillebotte: $25000\n- A bust of Diocletian: $5000\n- A Yuan dynasty Chinese vase: $20000\n- A 911 Porsche: $40000\n- Three diamonds: each $12000\n- A Louis XV sofa: $3000\n- Two very precious Jack Russell racing dogs: each $3000 (will stipulates they must not be separated)\n- A sculpture from 200 AD: $10000\n- A sailing boat: $15000\n- A Harley Davidson motorcycle: $10000\n- A piece of furniture once belonging to Cavour: $13000,\n\nwhich must be shared between two sons. How to formulate a mathematical program and solve it to minimize the difference in value between the two parts?", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "1000.0", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 31 (MIT)" + }, + { + "id": "lpmilp-033-bin-packing", + "question": "The current problem faced by the company is how to use the fewest number of containers to pack the currently needed goods for transportation, while considering the weight of the goods, specific packaging requirements, and inventory limitations. Professional modeling and analysis are needed for a batch of goods’ transportation strategy to ensure maximum utilization of the limited container space.\n\nThe company currently has a batch to be transported, with each container able to hold a maximum of 60 tons of goods and each container used must load at least 18 tons of goods. The goods to be loaded include five types: A, B, C, D, and E, with quantities of 120, 90, 300, 90, and 120 respectively. The weights are 0.5 tons for A, 1 ton for B, 0.4 tons for C, 0.6 tons for D, and 0.65 tons for E. Additionally, to meet specific usage requirements, every time A goods are loaded, at least 1 unit of C must also be loaded, but loading C alone does not require simultaneously loading A; and considering the demand limitation for D goods, each container must load at least 12 units of D.\n\nEstablish an operations research model so that the company can use the fewest number of containers to pack this batch of goods.", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "7.0", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 32 (MIT)" + }, + { + "id": "lpmilp-034-flow-shop-scheduling", + "question": "A fabric dyeing plant has 3 dyeing vats. Each batch of fabric must be dyed in sequence in each vat: first, the second, and third vats. The plant must color five batches of fabric of different sizes. The time required in hours to dye batch $i$ in vat $j$ is given in the following matrix:\n\n$$\n\\left(\\begin{array}{ccc}\n3 & 1 & 1 \\\\\n2 & 1.5 & 1 \\\\\n3 & 1.2 & 1.3 \\\\\n2 & 2 & 2 \\\\\n2.1 & 2 & 3\n\\end{array}\\right)\n$$\n\nSchedule the dyeing operations in the vats to minimize the completion time of the last batch.", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "14.1", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 33 (MIT)" + }, + { + "id": "lpmilp-035-capacitated-vehicle-routing-prob", + "question": "The Vehicle Routing Problem (VRP) was first proposed by Dantzig and Ramser in 1959. It is a classic combinatorial optimization problem. The basic VRP can be described as follows: in a certain area, there is a number of customers and a distribution center or depot. Customers are generally located at different positions, and each has a specific demand for goods. The distribution center needs to dispatch a fleet of vehicles and design appropriate delivery routes to fulfill the demands of all customers. The objective of VRP is to optimize a certain benefit metric while satisfying all customer demands. The benefit metric is usually presented as an objective function, which varies according to the company's requirements. Common objective functions include minimizing the total distance traveled by vehicles, minimizing the total delivery time, or minimizing the number of vehicles used. In addition to satisfying customer demands, VRP often needs to consider various other constraints, leading to several variants. For example, if the vehicle's load cannot exceed its maximum capacity, the problem becomes the Capacitated Vehicle Routing Problem (CVRP). If each customer's delivery must be made within a specific time frame, the problem becomes the Vehicle Routing Problem with Time Windows (VRPTW).\n\nThe Vehicle Routing Problem with Time Windows (VRPTW) is a classic variant of the VRP. There are many real-world applications of VRPTW, as customer locations often have service time windows. For instance, some logistics centers need to stock parcels during off-peak hours, and large supermarkets need to replenish goods outside of business hours. Real-time delivery services like food delivery also require strict delivery time windows. Time windows can be categorized as hard or soft. A Hard Time Window (HTW) means that a vehicle must arrive at the delivery point within or before the time window; late arrivals are not permitted. If a vehicle arrives early, it must wait until the time window opens to begin service. This is common in scenarios like supermarket restocking and logistics center inbound operations. A Soft Time Window (STW) means that a vehicle is not strictly required to arrive within the time window, but it is encouraged to do so. A penalty is incurred for early or late arrivals. This is applicable in scenarios such as meal delivery, school bus services, and industrial deliveries.\n\nThe Vehicle Routing Problem with Hard Time Windows (VRPHTW) can be described as follows: within a region, there is a set of customer locations and a central depot. Vehicles must start from the depot and return to the depot, following continuous paths. Each customer must be served by exactly one vehicle, and vehicles have a limited capacity. Each customer has a specific service time window, and service is only accepted within this window. A vehicle can arrive at a customer location early and wait for the time window to open, or it can arrive within the time window to provide service. Service can only begin within the time window, and the service duration is known. The distribution center must arrange an optimal delivery plan to both complete the delivery tasks and minimize travel costs. Because VRPHTW does not allow for delays, it, like the VRP, primarily emphasizes the minimization of travel costs along the routes.\n\n Now we consider a major enterprise logistics provider, 'Global Logistics', is responsible for providing precise material delivery services for multiple high-end office buildings and shops in a city's central business district (CBD). Due to traffic control in the CBD and the specific receiving requirements of the customers, the delivery task is highly challenging.\n\n**Specific Requirements:**\n\n1. **Delivery Task**: There are 20 customers requiring delivery service on the day, and the demands of all customers must be met.\n2. **Vehicle Constraints**: The company can use at most 5 trucks, and the capacity of each truck is 200 units.\n3. **Capacity Constraint**: The total demand of all customers on a single route must not exceed the truck's maximum capacity (200 units).\n4. **Time Window Constraint**: Each customer has a strict 'hard time window.' Service must begin within this specified time window. Early arrivals must wait, and late arrivals are not permitted.\n5. **Service Time**: Due to the complex handover procedures at customer sites, a fixed service time of 90 minutes is required for unloading, handover, and paperwork at each customer location.\n6. **Optimization Objective**: While satisfying all constraints, the company's objective is to **minimize the total distance traveled by all vehicles** to reduce operational costs.\n\n**Data Details:**\n\n* **Central Depot (Depot 0)**:\n * Coordinates: (40, 50)\n * Operating Time Window: [0, 1236] (minutes)\n* **Customer Locations (Customers 1-20)**: The coordinates, demand, service time window, and service duration for each customer are shown in the table below.\n\n| Customer ID | Coordinates (X, Y) | Demand (units) | Time Window (minutes) | Service Duration (minutes) |\n| :--- | :--- | :--- |:--- | :--- |\n| 1 | (45, 68) | 10 | [912, 967] | 90 |\n| 2 | (45, 70) | 30 | [825, 870] | 90 |\n| 3 | (42, 66) | 10 | [65, 146] | 90 |\n| 4 | (42, 68) | 10 | [727, 782] | 90 |\n| 5 | (42, 65) | 10 | [15, 67] | 90 |\n| 6 | (40, 69) | 20 | [621, 702] | 90 |\n| 7 | (40, 66) | 20 | [170, 225] | 90 |\n| 8 | (38, 68) | 20 | [255, 324] | 90 |\n| 9 | (38, 70) | 10 | [534, 605] | 90 |\n| 10 | (35, 66) | 10 | [357, 410] | 90 |\n| 11 | (35, 69) | 10 | [448, 505] | 90 |\n| 12 | (25, 85) | 20 | [652, 721] | 90 |\n| 13 | (22, 75) | 30 | [30, 92] | 90 |\n| 14 | (22, 85) | 10 | [567, 620] | 90 |\n| 15 | (20, 80) | 40 | [384, 429] | 90 |\n| 16 | (20, 85) | 40 | [475, 528] | 90 |\n| 17 | (18, 75) | 20 | [99, 148] | 90 |\n| 18 | (15, 75) | 20 | [179, 254] | 90 |\n| 19 | (15, 80) | 10 | [278, 345] | 90 |\n| 20 | (30, 50) | 10 | [10, 73] | 90 |\n\nNow, please provide an operations research model for this VRPHTW.", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "175.37", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 34 (MIT)" + }, + { + "id": "lpmilp-036-production-planning-problem", + "question": "A factory produces two types of microcomputers, A and B. Each type of microcomputer requires the same two production processes. The processing time, profit from sales, and the maximum weekly processing capacity for each type are shown in Table 3.1.\n\nTable 3.1\n\n| Process | Model | | Maximum Weekly Processing Capacity |\n| :---: | :---: | :---: | :---: |\n| | $\\\\mathrm{A}$ | $\\\\mathrm{B}$ | |\n| I (hours / unit) | 4 | 6 | 150 |\n| II (hours / unit) | 3 | 2 | 70 |\n| Profit ($ per unit) | 300 | 450 | |\n\nThe expected values for the factory's operational goals are as follows:\n\n$p_{1}$: The total weekly profit must not be less than $10,000.\n\n$p_{2}$: Due to contractual requirements, at least 10 units of Model A and at least 15 units of Model B must be produced per week.\n\n$p_{3}$: The weekly production time for Process I should be exactly 150 hours, and the production time for Process II should be fully utilized, with potential overtime if necessary.\n\nTry to establish the mathematical programming model for this problem in oder to maximize total profit.", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "11250.0", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 35 (MIT)" + }, + { + "id": "lpmilp-037-flow-shop-scheduling", + "question": "There are three different products to be processed on three machine tools. Each product must first be processed on machine 1, then sequentially on machines 2 and 3. The order of processing the three products on each machine should remain the same. Assuming $t_{ij}$ represents the time to process the $i$-th product on the $j$-th machine, how should the schedule be arranged to minimize the total processing cycle for the three products? The timetable is as follows:\n| Product | Machine 1 | Machine 2 | Machine 3 |\n|---------|-----------|-----------|-----------|\n| Product 1 | 2 | 3 | 1 |\n| Product 2 | 4 | 2 | 3 |\n| Product 3 | 3 | 5 | 2 |", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "14.0", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 36 (MIT)" + }, + { + "id": "lpmilp-038-transportation-airline-industry", + "question": "A company plans to transport goods between the city and the suburb and needs to choose the most environmentally friendly transportation method. The company can choose from the following three methods: motorcycle, small truck, and large truck. Each motorcycle trip produces 40 units of pollution, each small truck trip produces 70 units of pollution, and each large truck trip produces 100 units of pollution. The company's goal is to minimize total pollution.\n\nThe company can only choose two out of these three transportation methods.\n\nDue to certain road restrictions, the number of motorcycle trips cannot exceed 8.\n\nEach motorcycle trip can transport 10 units of products, each small truck trip can transport 20 units of products, and each large truck trip can transport 50 units of products. The company needs to transport at least 300 units of products.\n\nThe total number of trips must be less than or equal to 20.", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "600.0", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 37 (MIT)" + }, + { + "id": "lpmilp-039-production-planning-problem", + "question": "The independent country of Carelland mainly exports four commodities: steel, engines, electronic components, and plastic. Carelland's Minister of Finance (i.e., Minister of Economy) wants to maximize exports and minimize imports. The unit prices of steel, engines, electronics, and plastic on the world market are, in local currency (Klunz), 500, 1500, 300, 1200 respectively. Producing 1 unit of steel requires 0.02 units of engines, 0.01 units of plastic, 250 Klunz of other imported goods, and 6 person-months of labor. Producing 1 unit of engines requires 0.8 units of steel, 0.15 units of electronic components, 0.11 units of plastic, 300 Klunz of imported goods, and 1 person-year. One unit of electronics requires: 0.01 units of steel, 0.01 units of engines, 0.05 units of plastic, 50 Klunz of imported goods, and 6 person-months of labor. One unit of plastic requires: 0.03 units of engines, 0.2 units of steel, 0.05 units of electronic components, 300 Klunz of imported goods, and 2 person-years. Engine production is limited to 650000 units, and plastic production is limited to 60000 units. The total available labor force per year is 830000 person-months. Write a mathematical program to maximize domestic GDP and solve the problem.", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "36288567.0", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 38 (MIT)" + }, + { + "id": "lpmilp-040-profit-maximization-problem", + "question": "A person has a fund of 500,000 yuan and the following investment projects available in the next three years:\n\n(1) Investment can be made at the beginning of each year within three years, and the annual profit is 20% of the investment amount.\n\n(2) Investment is only allowed at the beginning of the first year, and can be recovered at the end of the second year, with the total principal and interest being 150% of the investment amount. However, this type of investment is limited to no more than 120,000 yuan.\n\n(3) Investment at the beginning of the second year, recoverable at the end of the second year, with the total principal and interest being 160% of the investment amount. This type of investment is limited to 150,000 yuan.\n\n(4) Investment is allowed at the beginning of the third year, recoverable in one year, with a profit of 40%, and the investment limit is 100,000 yuan.\n\nDetermine an investment plan for the person that maximizes the total principal and interest by the end of the third year.", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "964640.0", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 39 (MIT)" + }, + { + "id": "lpmilp-041-production-planning-problem", + "question": "Two steel furnaces at a steel plant each use two methods of steelmaking simultaneously. The first method takes $a=2$ hours per furnace and costs $m=50$ in fuel expenses; the second method takes $b=3$ hours per furnace and costs $n=70$ in fuel expenses. Assuming each furnace produces $k=10$ tons of steel regardless of the method used, and that at least $d=30$ tons of steel must be produced within $c=12$ hours, how should these two methods be allocated to minimize fuel expenses? Formulate this problem as a linear programming model.", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "150.0", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 40 (MIT)" + }, + { + "id": "lpmilp-042-transportation-problem", + "question": "A production base needs to extract raw materials from warehouses A and B every day for production. The required raw materials are: at least 240 pieces of raw material A, at least 80 kg of raw material B, and at least 120 tons of raw material C. It is known that: Each truck from warehouse A can transport back to the production base 4 pieces of raw material A, 2 kg of raw material B, 6 tons of raw material C, with a freight cost of 200 yuan per truck; each truck from warehouse B can transport back to the production base 7 pieces of raw material A, 2 kg of raw material B, 2 tons of raw material C per day, with a freight cost of 160 yuan per truck. Question: In order to meet production needs, how many trucks should be dispatched daily from warehouse A and warehouse B to minimize the total freight cost?", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "6800.0", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 41 (MIT)" + }, + { + "id": "lpmilp-043-capacitated-facility-location-pr", + "question": "Given that there are $m=2$ production points for a certain type of material, where the output at the $i$-th point $(i=1,2)$ is $a_i$, $a_1 = 100$, and $a_2 = 150$. This material is to be shipped to $n=2$ demand points, where the demand at the $j$-th point $(j=1, 2)$ is $b_j$, $b_1 = 80$, and $b_2 = 120$. It is known that $\\sum_i a_i \\geqslant \\sum_j b_j$. It is also known that when shipping from production points to demand points, it must pass through one of the $p=2$ intermediate marshaling stations. If the $k$-th $(k=1, 2)$ intermediate marshaling station is used, a fixed cost $f_k$ is incurred regardless of the transshipment volume, where $f_1 = 10$ and $f_2 = 15$. The $k$-th intermediate marshaling station has a maximum transshipment capacity limitation $q_k$, where $q_1 = 100$ and $q_2 = 100$. Let $c_{i k}$ and $c'_{k j}$ denote the unit transportation cost from $i$ to $k$ and from $k$ to $j$, respectively, where $c_{11}=2$, $c_{12}=3$, $c_{21}=4$, $c_{22}=1$, $c'_{11}=3$, $c'_{12}=2$, $c'_{21}=1$, and $c'_{22}=4$. Try to determine a transportation plan for this material that minimizes the total cost.", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "685.0", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 42 (MIT)" + }, + { + "id": "lpmilp-044-production-planning-problem", + "question": "A factory produces three types of products, A, B, and C. Each unit of product A requires 1 hour for technical preparation, 10 hours of direct labor, and 3 kg of materials. Each unit of product B requires 2 hours for technical preparation, 4 hours of labor, and 2 kg of materials. Each unit of product C requires 1 hour for technical preparation, 5 hours of labor, and 1 kg of materials. The available technical preparation time is 100 hours, labor time is 700 hours, and materials are 400 kg. The company offers larger discounts for bulk purchases, as detailed in Table 1-22. Determine the company's production plan to maximize profit.\nTable 1-22\n| Product A | | Product B | | Product C | |\n|:---------------|:---------:|:---------------|:---------:|:---------------|:---------:|\n| Sales Volume (pieces) | Profit (yuan) | Sales Volume (pieces) | Profit (yuan) | Sales Volume (pieces) | Profit (yuan) |\n| 0 ~ 40 | 10 | 0 ~ 50 | 6 | 0 ~ 100 | 5 |\n| 40 ~ 100 | 9 | 50 ~ 100 | 4 | Above 100 | 4 |\n| 100 ~ 150 | 8 | Above 100 | 3 | | |\n| Above 150 | 7 | | | | |", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "712.0", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 43 (MIT)" + }, + { + "id": "lpmilp-045-assignment-problem", + "question": "A university computer lab hires 4 undergraduates (designated 1, 2, 3, and 4) and 2 graduate students (designated 5 and 6) for duty answering questions. The maximum duty hours from Monday to Friday and the hourly wage for each person are shown in Table 5-9.\n\nTable 5-9\nStudent ID | Wage (CNY/h) | Monday | Tuesday | Wednesday | Thursday | Friday\n1 | 10.0 | 6 | 0 | 6 | 0 | 7\n2 | 10.0 | 0 | 6 | 0 | 6 | 7\n3 | 9.9 | 4 | 8 | 4 | 0 | 5\n4 | 9.8 | 5 | 5 | 6 | 0 | 4\n5 | 10.8 | 4 | 0 | 4 | 8 | 0\n6 | 11.3 | 5 | 6 | 0 | 6 | 3\n\nThe lab operates from 8:00 AM to 10:00 PM, and there must be one and only one student on duty during open hours. It is also required that each undergraduate must work at least 8 hours per week, and each graduate student must work at least 7 hours per week. Additionally, each student can work no more than 2 shifts per week, and no more than 3 students can be scheduled for duty each day.\n\nBased on these conditions, establish a mathematical model to determine the work schedule that satisfies all requirements.", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "717.9", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 44 (MIT)" + }, + { + "id": "lpmilp-046-farm-planning", + "question": "A certain farm has 100 hectares of land and 15,000 yuan in funds for production development. The labor force situation on the farm is 3,500 person-days in autumn and winter, and 4,000 person-days in spring and summer. If the labor force itself is not fully utilized, they can work externally, earning 2.1 yuan/person-day in spring and summer and 1.8 yuan/person-day in autumn and winter.\n\nThe farm cultivates three types of crops: soybeans, corn, and wheat, and also raises dairy cows and chickens. Crop cultivation requires no specialized investment, but raising animals involves an investment of 400 yuan per dairy cow and 3 yuan per chicken. Raising dairy cows requires allocating 1.5 hectares of land per cow to grow feed, and involves 100 person-days in autumn and winter, and 50 person-days in spring and summer per cow. The annual net income is 400 yuan per dairy cow. Raising chickens does not use land, requires 0.6 person-days in autumn and winter, and 0.3 person-days in spring and summer per chicken. Annual net income is 2 yuan per chicken. The current chicken coop can accommodate up to 3,000 chickens, and the cow barn can accommodate up to 32 dairy cows. The labor and income requirements for the three types of crops per year are shown in Table 1-9.\n\nTable 1-9\n| Item | Soybean | Corn | Wheat |\n|----------------|---------|------|-------|\n| Person-days (Autumn/Winter) | 20 | 35 | 10 |\n| Person-days (Spring/Summer) | 50 | 75 | 40 |\n| Annual Net Income (Yuan/hectare) | 175 | 300 | 120 |\n\nDetermine the farm's operating plan to maximize annual net income. Please note that workers can only work externally for full days, fractions are not allowed. It is not possible to change the crop and animal raising plans from season to season.", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "20241.8", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 45 (MIT)" + }, + { + "id": "lpmilp-047-production-planning-problem", + "question": "A factory produces two models of microcomputers, A and B. Each model requires the same two processes. The processing time, sales profit, and the factory’s maximum weekly processing capacity for each model are shown in Table 3.1.\n\nTable 3.1\n\n| Process | Model | | Maximum Weekly Processing Capacity |\n| :---: | :---: | :---: | :---: |\n| | $A$ | $B$ | |\n| I (hours/unit) | 4 | 6 | 150 |\n| II (hours/unit) | 3 | 2 | 70 |\n| Profit (yuan/unit) | 300 | 450 | |\n\nGiven the factory's business goals:\n\n$p_{1}$: The total weekly profit should not be less than 10,000 yuan;\n\n$p_{2}$: Due to contract requirements, at least 10 units of model A and at least 15 units of model B must be produced each week;\n\n$p_{3}$: The processing time for Process I should be exactly 150 hours per week, and the processing time for Process II should ideally be fully utilized, with potential for appropriate overtime;\n\n$p_{4}$: If products are produced during overtime in Process II, the profit per unit is reduced by 20 yuan for model A and 25 yuan for model B, and the maximum overtime for Process II is 30 hours per week. Formulate the mathematical model for this problem.", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "11250.0", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 46 (MIT)" + }, + { + "id": "lpmilp-048-lot-sizing-problem", + "question": "A factory must rent warehouse space to cover storage needs over the next four months. The required storage areas are:\nMonth 1: 1500 m²\nMonth 2: 1000 m²\nMonth 3: 2000 m²\nMonth 4: 1200 m²\n\nWarehouse space can be rented via contracts of fixed duration. A contract of length k months (k ? {1, 2, 3, 4}) may start at the beginning of any month t provided it ends no later than Month 4 (i.e., t + k ? 1 ? 4). A contract starting in month t covers months t through t + k ? 1. The rental fee is charged per square meter per month and depends on the contract length as follows:\n1-month contract: 22 yuan per m² per month\n2-month contract: 21 yuan per m² per month\n3-month contract: 20 yuan per m² per month\n4-month contract: 19 yuan per m² per month\n\nAdditional rules and assumptions:\n\nYou may sign any number of contracts.\n\nRented area is divisible (you may rent any nonnegative real number of m²).\n\nSupply is unlimited at the listed rates.\n\nIn each month, the total active rented area must be at least the required area for that month.\n\nYou pay for the entire area specified in each contract for every month it is active, even if some capacity is unused.\n\nYour task is to choose the start times, durations, and areas of contracts to minimize the total rental cost over the four-month horizon while satisfying the monthly area requirements.", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "113000.0", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 47 (MIT)" + }, + { + "id": "lpmilp-049-lot-sizing-problem", + "question": "A store has formulated a purchase and sales plan for a certain product from July to December. It is known that the warehouse capacity must not exceed 500 units, with 200 units in stock at the end of June. Thereafter, purchases are made at the beginning of each month. Assume the purchase and selling prices of this product for each month are shown in Table 1-21. How much should be purchased and sold each month to maximize the total revenue?\n\nTable 1-21\n| Month | 7 | 8 | 9 | 10 | 11 | 12 |\n|-------|----|----|----|----|----|----|\n| Buy | 28 | 24 | 25 | 27 | 23 | 23 |\n| Sell | 29 | 24 | 26 | 28 | 22 | 25 |", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "9100.0", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 48 (MIT)" + }, + { + "id": "lpmilp-050-military-personnel-deployment-pr", + "question": "The number of nurses required in each time period over 24 hours at a certain hospital is as follows: 2:00-6:00 - 10 people, 6:00-10:00 - 15 people, 10:00-14:00 - 25 people, 14:00-18:00 - 20 people, 18:00-22:00 - 18 people, 22:00-2:00 - 12 people. Nurses start shifts in 6 batches at 2:00, 6:00, 10:00, 14:00, 18:00, and 22:00 and work continuously for 8 hours. Please determine: If the hospital can hire contract nurses with the same working hours as regular nurses, and if the pay for regular nurses is 10 yuan/hour and for contract nurses is 15 yuan/hour, should the hospital hire contract nurses and if so, how many?", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "4240.0", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 49 (MIT)" + }, + { + "id": "lpmilp-051-set-multi-cover", + "question": "For a certain 24-hour bus service, the number of drivers and crew members required during different time periods each day is shown in Table 1-2:\nTable 1-2\n\\begin{tabular}{|c|c|c||c|c|c|}\n\\hline Shift & Time & Required number & Shift & Time & Required number \\\\\n\\hline 1 & $6: 00 \\sim 10: 00$ & 60 & 4 & $18 ; 00 \\sim 22 ; 00$ & 50 \\\\\n\\hline 2 & $10 ; 00 \\sim 14 ; 00$ & 70 & 5 & $22 ; 00 \\sim 2 ; 00$ & 20 \\\\\n\\hline 3 & $14 ; 00 \\sim 18 ; 00$ & 60 & 6 & $2: 00 \\sim 6 ; 00$ & 30 \\\\\n\\hline\n\\end{tabular}\n\nAssuming that drivers and crew members start their shifts at the beginning of each time period and work continuously for 8 hours, determine the minimum number of drivers and crew members needed for this bus route. Formulate the linear programming model for this problem.", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "150.0", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 50 (MIT)" + }, + { + "id": "lpmilp-052-knapsack", + "question": "The Zhang family has 6 children: Harry, Hermione, Ron, Fred, George, and Ginny. The cost of taking Harry is $1200, Hermione is $1650, Ron is $750, Fred is $800, George is $800, and Ginny is $1500. Which children should the couple take to minimize the total cost of taking the children? They can take up to four children on the upcoming trip.\n\nGinny is the youngest, so the Zhang family will definitely take her.\n\nIf the couple takes Harry, they will not take Fred because Harry does not get along with him.\n\nIf the couple takes Harry, they will not take George because Harry does not get along with him.\n\nIf they take George, they must also take Fred.\n\nIf they take George, they must also take Hermione.\n\nEven though it will cost them a lot of money, the Zhang family has decided to take at least three children.", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "3050.0", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 51 (MIT)" + }, + { + "id": "lpmilp-053-production-planning-problem", + "question": "Given that a certain factory plans to produce three types of products, I, II, and III, each product needs to be processed on equipment $A, B, C$ as shown in Table 2-3:\n\nTable 2-3\n| Equipment Code | I | II | III | Effective Monthly Equipment Hours |\n|----------------|----|----|-----|----------------------------------|\n| A | 8 | 2 | 10 | 300 |\n| B | 10 | 5 | 8 | 400 |\n| C | 2 | 13 | 10 | 420 |\n| Unit Product Profit (per thousand yuan) | 3 | 2 | 2.9 | |\n\nHow can the equipment capacity be fully utilized to maximize production profit? The quantity of each product must be an integer.", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "134.5", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 52 (MIT)" + }, + { + "id": "lpmilp-054-set-multi-cover", + "question": "A master's student in Operations Research at a certain university is required to select two courses in mathematics, two in operations research, and two in computer science from a total of seven courses: Calculus, Operations Research, Data Structures, Management Statistics, Computer Simulation, Computer Programming, and Forecasting. Some courses belong to only one category: Calculus falls under Mathematics, Computer Programming under Computer Science. However, some courses fall under multiple categories: Operations Research can be considered both Operations Research and Mathematics, Data Structures both Computer Science and Mathematics, Management Statistics both Mathematics and Operations Research, Computer Simulation both Computer Science and Operations Research, and Forecasting both Operations Research and Mathematics. Courses that fall under multiple categories can fulfill the requirement of both categories simultaneously. Additionally, some courses have prerequisites: Computer Simulation or Data Structures requires Computer Programming first, Management Statistics requires Calculus first, and Forecasting requires Management Statistics first. The question is: What is the minimum number of courses a master's student must take, and which specific courses, to meet the above requirements?", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "4.0", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 53 (MIT)" + }, + { + "id": "lpmilp-055-lot-sizing-problem", + "question": "A trading company specializes in the wholesale business of certain grains. The company currently has a warehouse with a capacity of 5000 dan. On January 1, the company has 1000 dan of grain in stock and 20,000 yuan in funds. The estimated grain prices for the first quarter are shown in Table 1-8.\n\nTable 1-8\n| Month | Purchase Price (yuan/dan) | Selling Price (yuan/dan) |\n|-------|---------------------------|--------------------------|\n| 1 | 2.85 | 3.10 |\n| 2 | 3.05 | 3.25 |\n| 3 | 2.90 | 2.95 |\n\nThe purchased grains will be delivered in the same month but can only be sold in the next month, and payment is required upon delivery. The company hopes to have an inventory of 2000 dan at the end of the quarter. What purchasing and selling strategy should be adopted to maximize the total profit over the three months?", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "-700.0", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 54 (MIT)" + }, + { + "id": "lpmilp-056-cutting-stock-problem", + "question": "Assuming a paper mill receives three orders for rolls of paper, with length and width requirements as shown in Table 1.2.\n\nTable 1.2\n\n| Order Number | Width (meters) | Length (meters) |\n| :---: | :---: | :---: |\n| 1 | 0.5 | 1000 |\n| 2 | 0.7 | 3000 |\n| 3 | 0.9 | 2000 |\n\nThe mill produces rolls of paper with standard widths of 1 meter and 2 meters. Assuming the length of the rolls is unlimited and can be spliced to reach the required length, how should the rolls be cut to minimize the area of waste?", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "600.0", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 55 (MIT)" + }, + { + "id": "lpmilp-057-farm-planning", + "question": "Vicky and David have just bought a farm in the Yarra Valley, and they are considering using it to grow apples, pears, oranges, and lemons. The profit for growing one acre of apples is $2000, for one acre of pears is $1800, for one acre of oranges is $2200, and for one acre of lemons is $3000. To achieve maximum profit, how many acres of land should they use to grow each type of fruit? Vicky and David have just bought a farm in the Yarra Valley with a total area of 120 acres.\n\nThe land used to grow apples should be at least twice the land used to grow pears.\n\nThe land used to grow apples should be at least three times the land used to grow lemons.\n\nThe land used to grow oranges must be twice the land used to grow lemons if lemons are grown. If no lemons are grown, then we do not have this constraint.\n\nVicky and David are unwilling to grow more than two types of fruit.", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "264000.0", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 56 (MIT)" + }, + { + "id": "lpmilp-058-blending-problem", + "question": "A candy factory uses raw materials A, B, and C to process three different brands of candies, A, B, and C. It is known that the content of A, B, and C in each brand of candy, the cost of raw materials, the monthly limit of each raw material, and the unit processing fee and selling price of the three brands of candies are shown in Table 1-7.\n\nTable 1-7\n\n| Item | A | B | C | Raw Material Cost (Yuan/kg) | Monthly Limit (kg) |\n|:----------------|:---------------|:---------------|:---------------|:-----------------------------|:-------------------|\n| A | ? 60% | ? 15% | | 2.00 | 2000 |\n| B | | | | 1.50 | 2500 |\n| C | ? 20% | ? 60% | ? 50% | 1.00 | 1200 |\n| Processing Fee (Yuan/kg) | 0.50 | 0.40 | 0.30 | | |\n| Selling Price (Yuan/kg) | 3.40 | 2.85 | 2.25 | | |\n\nHow many kilograms of each of the three brands of candies should the factory produce each month to maximize the profit?", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "6160.0", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 57 (MIT)" + }, + { + "id": "lpmilp-059-travelingsalesman", + "question": "A traveling salesman must visit 7 customers at 7 different locations, with the (symmetric) distance matrix as follows:\n\n| | 1 | 2 | 3 | 4 | 5 | 6 | 7 |\n| :---: | :---: | :---: | :---: | :---: | :---: | :---: | :---: |\n| 1 | - | 86 | 49 | 57 | 31 | 69 | 50 |\n| 2 | | - | 68 | 79 | 93 | 24 | 5 |\n| 3 | | | - | 16 | 7 | 72 | 67 |\n| 4 | | | | - | 90 | 69 | 1 |\n| 5 | | | | | - | 86 | 59 |\n| 6 | | | | | | - | 81 |\n\nFormulate a mathematical program to determine the visiting order starting and ending at location 1 to minimize the travel distance.", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "153.0", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 58 (MIT)" + }, + { + "id": "lpmilp-060-capacitated-facility-location-pr", + "question": "A product can be processed on any one of the four devices: A, B, C, or D. The preparation completion costs when each device is enabled, the unit production cost for the product, and the maximum processing capacity of each device are shown in Table 5-7. If 2000 units of the product need to be produced, how can the total cost be minimized? Try to establish a mathematical model.\n\nTable 5-7\n| Device | Prep Completion Cost (Yuan) | Unit Production Cost (Yuan/Unit) | Maximum Processing Capacity (Units) |\n|--------|------------------------------|----------------------------------|------------------------------------|\n| A | 1000 | 20 | 900 |\n| B | 920 | 24 | 1000 |\n| C | 800 | 16 | 1200 |\n| D | 700 | 28 | 1600 |", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "37000.0", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 59 (MIT)" + }, + { + "id": "lpmilp-061-knapsack", + "question": "The Zhang family is deciding to invest in several different restaurants. The annual revenue of Restaurant A is $15,000, Restaurant B is $40,000, Restaurant C is $30,000, and Restaurant D is $50,000. They need to decide whether to purchase each restaurant, with each restaurant being able to be purchased only once. Help them decide which restaurants to buy to maximize their annual income.\nThe cost of Restaurant A is 1.6 million, Restaurant B is 2.5 million, Restaurant C is 1.8 million, and Restaurant D is 3 million. The Zhang family's investment budget is 6 million.\n\nIf they purchase Restaurant D, then they cannot purchase Restaurant A.", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "90000.0", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 60 (MIT)" + }, + { + "id": "lpmilp-062-transportation-problem", + "question": "A farmer needs to transport 1000 units of fresh produce from the farm to a nearby market. The farmer has three transportation options: a horse, a bicycle, and a handcart. Since both the bicycle and handcart are very physically demanding, the farmer wants to choose only one of these two transportation methods. The horse generates 80 units of pollution per trip, the bicycle generates 0 units of pollution, and the handcart generates 0 units of pollution. The total amount of pollution generated by all trips must not exceed 1000 units. At least 8 trips must be made using the horse. The horse, bicycle, and handcart can carry 55 units, 30 units, and 40 units of produce per trip respectively. The farmer needs to ensure that the total amount of transported produce is at least 1000 units while minimizing the total amount of pollution. What is the minimum amount of pollution that the farmer can achieve?", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "640.0", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 61 (MIT)" + }, + { + "id": "lpmilp-063-knapsack", + "question": "A company needs to decide whether to hire some of the five candidates to join their R&D team. The salary requirements for candidates F, G, H, I, and J are $12,000, $15,000, $18,000, $5,000, and $10,000 respectively. The company wants to minimize the total amount paid to candidates without exceeding the budget.\n\nThe company's budget is $40,000 and they wish to hire a maximum of 4 new employees.\n\nThe skill levels of the candidates are as follows:\nCandidate F: Level 2\nCandidate G: Level 3\nCandidate H: Level 4\nCandidate I: Level 1\nCandidate J: Level 2\n\nThe company needs to ensure that the total skill level of the hired employees is at least 8.\n\nThe project management experience years of each candidate are as follows:\nCandidate F: 1 year\nCandidate G: 2 years\nCandidate H: 2 years\nCandidate I: 5 years\nCandidate J: 4 years\n\nThey hope the total project management experience of the team is at least 8 years.\n\nDue to the similar technical background of candidates G and J, the company can choose at most one of them.", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "38000.0", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 62 (MIT)" + }, + { + "id": "lpmilp-064-production-planning-problem", + "question": "A company produces two types of products: microwave ovens and water heaters, which are manufactured in both workshops A and B. It is known that apart from the purchased parts, the production of one microwave oven requires 2 hours of processing in workshop A and 1 hour of assembly in workshop B. The production of one water heater requires 1 hour of processing in workshop A and 3 hours of assembly in workshop B. After production, both products need inspection, sales, and other procedures. The inspection and sales cost for each microwave oven is 30 yuan, and for each water heater is 50 yuan. Workshop A has 250 hours of available production time per month, with each hour costing 80 yuan; workshop B has 150 hours of available production time per month, with each hour costing 20 yuan. It is estimated that an average of 80 microwave ovens and 50 water heaters can be sold per month next year. Based on these actual conditions, the company has established the following monthly plan constraints:\n\n1. Inspection and sales costs should not exceed 5500 yuan per month;\n2. At least 80 microwave ovens should be sold per month;\n3. The production hours of both workshops A and B should be fully utilized, and overtime for workshop A and B are allowed.\n4. Overtime in workshop A should not exceed 20 hours; we do not have upper limit on workshop B's overtime.\n5. At least 50 water heaters should be sold per month.\n\nTry to determine the monthly production plan for the company.", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "30500.0", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 63 (MIT)" + }, + { + "id": "lpmilp-065-production-planning-problem", + "question": "A toy company manufactures three types of tabletop golf toys, each requiring different manufacturing techniques. The high-end type requires 17 hours of manufacturing labor, 8 hours of inspection, and yields a profit of 300 yuan per unit. The mid-range type requires 10 hours of labor, 4 hours of inspection, and yields a profit of 200 yuan per unit. The low-end type requires 2 hours of labor, 2 hours of inspection, and yields a profit of 100 yuan per unit. Available labor hours are 1000, and available inspection hours are 500. Additionally, market forecasts indicate a demand of no more than 50 units for the high-end type, no more than 80 units for the mid-range type, and no more than 150 units for the low-end type. Determine the production plan for the company to maximize profit.", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "25000.0", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 64 (MIT)" + }, + { + "id": "lpmilp-066-lot-sizing-problem", + "question": "The market demand for products I and II is as follows: Product I requires 10,000 units per month from January to April, 30,000 units per month from May to September, and 100,000 units per month from October to December. Product II requires 15,000 units per month from March to September and 50,000 units per month during other months. The cost of producing these two products at a certain factory is as follows: Product I costs 5 yuan per unit to produce from January to May, and 4.50 yuan per unit from June to December; Product II costs 8 yuan per unit to produce from January to May, and 7 yuan per unit from June to December. The factory's combined production capacity for both products should not exceed 120,000 units per month. Product I has a volume of 0.2 cubic meters per unit, Product II has a volume of 0.4 cubic meters per unit, and the factory's warehouse capacity is 15,000 cubic meters. If the factory's warehouse space is insufficient, external warehouse space can be rented. Using the factory’s own warehouse costs 1 yuan per cubic meter per month, while renting an external warehouse increases this cost to 1.5 yuan per cubic meter per month. Given that the initial inventory of both products at the beginning of July is zero, how should production be scheduled from July to December to minimize the total production and inventory costs while meeting market demand?", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "3160500.0", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 65 (MIT)" + }, + { + "id": "lpmilp-067-transportation-problem", + "question": "There are two coal yards A and B, each receiving no less than 80 tons and 100 tons of coal per month, respectively. They are responsible for supplying coal to three residential areas, which need 55 tons, 75 tons, and 50 tons of coal per month, respectively. Coal yard A is located 10 kilometers, 5 kilometers, and 6 kilometers from these three residential areas. Coal yard B is located 4 kilometers, 8 kilometers, and 15 kilometers from these three residential areas. How should these two coal yards distribute coal to the three residential areas to minimize the ton-kilometers of transportation?", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "1030.0", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 66 (MIT)" + }, + { + "id": "lpmilp-068-cutting-stock-problem", + "question": "A steel reinforcement workshop produces a batch of steel bars (with the same diameter), consisting of 90 pieces of 3 meters in length and 60 pieces of 4 meters in length. It is known that each piece of raw steel bar used is 10 meters in length. How can the raw material be cut most efficiently? Establish a linear programming model for this problem.", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "53.0", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 67 (MIT)" + }, + { + "id": "lpmilp-069-travelingsalesman", + "question": "The famous Traveling Salesman Problem (TSP) in operations research can be described as follows: A traveling salesman departs from a certain city, and must visit each city exactly once before returning to the original starting city. The distances between the cities are provided in the table below (the entry at row i and column j represents the cost of going from city i to city j)\n| City | 1 | 2 | 3 | 4 |\n| ---- | ------ | ------ | ------ | ------ |\n| 1 | 0 | 10 | 20 | 12 |\n| 2 | 10 | 0 | 5 | 10 |\n| 3 | 20 | 5 | 0 | 8 |\n| 4 | 15 | 12 | 8 | 0 |\n\nWhat route should the salesman choose to travel in order to minimize the total distance? Try to formulate an integer programming model for this problem.", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "35.0", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 68 (MIT)" + }, + { + "id": "lpmilp-070-assignment-problem", + "question": "Consider assigning $n=2$ factories to $n$ locations. The transportation volume between factory $i$ and factory $j$ is $d_{ij}$, and the unit transportation cost from location $p$ to location $q$ is $c_{pq}$. The specific values are shown in the following table: Table 1.1\n\n| | Transportation volume to Location 1 | Transportation volume to Location 2 | Transportation cost to Location 1 | Transportation cost to Location 2 |\n| :----: | :---------------------------------: | :---------------------------------: | :-------------------------------: | :-------------------------------: |\n| Factory 1 | 10 | 20 | 5 | 8 |\n| Factory 2 | 30 | 40 | 6 | 7 |\n\nIn order to minimize the total transportation cost, formulate this problem as an integer model.", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "330.0", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 69 (MIT)" + }, + { + "id": "lpmilp-071-knapsack", + "question": "The Li family plans to invest their retirement fund in commercial real estate. The annual income from Property 1 is $12,500, Property 2 is $35,000, Property 3 is $23,000, and Property 4 is $100,000. The decision to be made is whether to buy each property or not, rather than how many to buy, as there is only one of each property available. Help them decide which properties to purchase to maximize their annual income.\n\nThe cost of Property 1 is $1.5 million, Property 2 is $2.1 million, Property 3 is $2.3 million, and Property 4 is $4.2 million. The Li family's budget is $7 million.\n\nIf they purchase Property 4, they cannot purchase Property 3.", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "135000.0", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 70 (MIT)" + }, + { + "id": "lpmilp-072-knapsack", + "question": "The Li family has 5 children: Alice, Bob, Charlie, Diana, and Ella. The cost to take Alice is $1000, Bob is $900, Charlie is $600, Diana is $500, and Ella is $700. Which children should the couple take to minimize the total cost of taking the children?\n\nThey can take up to 3 children on the upcoming trip.\n\nBob is the youngest, so the Li family will definitely take him.\n\nIf the couple takes Alice, they will not take Diana because Alice does not get along with her.\n\nIf the couple takes Bob, they will not take Charlie because Bob does not get along with him.\n\nIf they take Charlie, they must also take Diana.\n\nIf they take Diana, they must also take Ella.\n\nDespite the cost, the Li family has decided to take at least two children.", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "1600.0", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 71 (MIT)" + }, + { + "id": "lpmilp-073-operations-optimization", + "question": "A project includes the following 7 activities, with their durations (in days) as follows: $A(4), B(3), C(5), D(2), E(10), F(10), G(1)$. The precedence relationships are also given as: $A \\rightarrow G, D ; E, G \\rightarrow F; D, F \\rightarrow C ; F \\rightarrow B$. The cost of work per day is 1000 Euros; additionally, a special machine must be rented from the start of activity $A$ to the end of activity $B$, costing 5000 Euros per day. Formulate this as a linear programming problem to minimize cost and complete all activities.", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "115000.0", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 72 (MIT)" + }, + { + "id": "lpmilp-074-production-planning-problem", + "question": "There are $\\mathrm{A}$ and $\\mathrm{B}$ two products, both requiring two successive chemical reaction processes. Each unit of product $\\mathrm{A}$ needs 2 hours for the first process and 3 hours for the second process. Each unit of product $\\mathrm{B}$ needs 3 hours for the first process and 4 hours for the second process. Available time for the first process is 16 hours, and available time for the second process is 24 hours.\n\nFor each unit of product $\\mathrm{B}$ produced, 2 units of by-product $\\mathrm{C}$ are generated simultaneously, requiring no additional cost. By-product $\\mathrm{C}$ can be sold up to 5 units, and the rest must be disposed of at a cost of 2 yuan per unit.\n\nEach unit of product $\\mathrm{A}$ sold yields a profit of 4 yuan, each unit of product $\\mathrm{B}$ yields a profit of 10 yuan, and each unit of by-product $\\mathrm{C}$ sold yields a profit of 3 yuan.\n\nIn order to maximize total profit, establish the linear programming model for this problem.", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "57.0", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 73 (MIT)" + }, + { + "id": "lpmilp-075-lot-sizing-problem", + "question": "A timber storage and transport company has a large warehouse for storing and transporting timber for sale. Due to seasonal price fluctuations, the company purchases timber at the beginning of each quarter, with part of it being sold within the quarter and part being stored for future sales. It is known that the maximum storage capacity of the company's warehouse is 200,000 m³, and the storage cost is $(a+b u)$ yuan/m³, where $a=70$, $b=100$, and $u$ is the storage time (in quarters). The purchase and sale prices for each quarter and the estimated maximum sales volumes are shown in Table 1-18.\n\nTable 1-18\n| Quarter | Purchase Price (10,000 yuan/10,000 m²) | Sale Price (10,000 yuan/10,000 m²) | Estimated Maximum Sales Volume (10,000 m³) |\n|---------|----------------------------------------|------------------------------------|---------------------------------------------|\n| Winter | 410 | 425 | 100 |\n| Spring | 430 | 440 | 140 |\n| Summer | 460 | 465 | 200 |\n| Autumn | 450 | 455 | 160 |\n\nSince timber is not suitable for long-term storage, all inventory should be sold by the end of autumn. Try to establish a linear programming model for this problem to maximize the company's annual profit. Return your answer in the unit of 10000 yuan.", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "4700.0", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 74 (MIT)" + }, + { + "id": "lpmilp-076-capacitated-facility-location-pr", + "question": "There are 10 different parts, and they can all be processed on machine \\( A \\), machine \\( B \\), or machine \\( C \\). The unit processing costs are shown in Table 5-6. Additionally, as long as any part is processed on the aforementioned machines, a one-time setup cost will be incurred regardless of whether one or multiple types of parts are processed, with the respective costs being \\( d_A = 100 \\), \\( d_B = 135 \\), and \\( d_C = 200 \\) yuan. If the requirements are:\n\n1. One piece of each of the aforementioned 10 types of parts needs to be processed;\n2. If the 1st part is processed on machine \\( A \\), then the 2nd part must be processed on machine \\( B \\) or \\( C \\); conversely, if the 1st part is processed on machine \\( B \\) or \\( C \\), then the 2nd part must be processed on machine \\( A \\);\n3. Parts 3, 4, and 5 must be processed on machines A, B, and C respectively;\n4. The number of parts processed on machine \\( C \\) should not exceed 3 types.\n\nTry to establish an integer programming mathematical model for this problem with the objective of minimizing the total cost.\n\nTable 5-6\n| Machine/Part | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 |\n|--------------|-----|-----|-----|-----|-----|-----|-----|-----|-----|-----|\n| A | $10$ | $20$ | $30$ | $40$ | $50$ | $60$ | $70$ | $80$ | $90$ | $100$ |\n| B | $15$ | $25$ | $35$ | $45$ | $55$ | $65$ | $75$ | $85$ | $95$ | $105$ |\n| C | $20$ | $30$ | $40$ | $50$ | $60$ | $70$ | $80$ | $90$ | $100$ | $110$ |", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "1005.0", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 75 (MIT)" + }, + { + "id": "lpmilp-077-operations-optimization", + "question": "A shoe store employs 5 full-time sales clerks and 4 part-time sales clerks. Their working hours and wage conditions are shown in Table 3.3.\n\nTable 3.3\n\n| | Monthly Working Hours | Sales Volume (Pairs/Hour) | Wage (Yuan/Hour) | Overtime Pay (Yuan/Hour) |\n| :---: | :---: | :---: | :---: | :---: |\n| Full-time | 160 | 5 | 1 | 1.5 |\n| Part-time | 80 | 2 | 0.6 | 0.7 |\n\nEach pair of shoes sold earns a profit of 0.3 yuan. The store has set the following goals:\n\n$p_{1}$: Achieve monthly sales of 5500 pairs;\n\n$p_{2}$: Ensure full employment of all sales clerks;\n\n$p_{3}$: Minimize overtime hours.\n\nTry to establish a model for this problem.", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "172.0", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 76 (MIT)" + }, + { + "id": "lpmilp-078-production-planning-problem", + "question": "A furniture factory needs to decide how many tables, chairs, and bookshelves to produce in order to maximize its profit. The factory can sell each table for $200, each chair for $50, and each bookshelf for $150. The manufacturing costs for each table, chair, and bookshelf are $120, $20, and $90 respectively. The profit is the difference between the selling price and the manufacturing cost. Each table, chair, and bookshelf occupy 5, 2, and 3 square meters of warehouse space respectively. Due to limited warehouse space, the total space cannot exceed 500 square meters. In addition, due to market demand, the factory needs to produce at least 10 tables and 20 bookshelves. Finally, the total number of items produced by the factory cannot exceed 200.", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "9800.0", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 77 (MIT)" + }, + { + "id": "lpmilp-079-operations-optimization", + "question": "A company requires skilled workers and laborers for three tasks. The first task can be completed by one skilled worker alone, or by a group of one skilled worker and two laborers. The second task can be done by one skilled worker or one laborer alone. The third task can be completed by a group of five laborers, or by one skilled worker leading three laborers. The weekly wages for skilled workers and laborers are 100 yuan and 80 yuan respectively. They work 48 hours per week, but their actual effective working hours are 42 hours and 36 hours respectively. To complete these tasks, the company needs a total effective working time of 8400 hours for the first task, 10800 hours for the second task, and 18000 hours for the third task per week. The number of workers that can be recruited is limited to a maximum of 400 skilled workers and 800 laborers. Establish a mathematical model to determine how many skilled workers and laborers should be hired in order to minimize the total wage expenditure.", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "84000.0", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 78 (MIT)" + }, + { + "id": "lpmilp-080-assignment-problem", + "question": "On Danzig Street, vehicles can park on both sides of the street. Mr. Edmonds, who lives at No. 1, is organizing a party with about 30 participants, and they will arrive in 15 cars. The length of the i-th car is ?_i, in meters, as follows:\n\n| i | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 |\n|----|----|-----|----|-----|-----|-----|-----|-----|-----|-----|-----|-----|-----|-----|-----|\n| ?_i | 4 | 4.5 | 5 | 4.1 | 2.4 | 5.2 | 3.7 | 3.5 | 3.2 | 4.5 | 2.3 | 3.3 | 3.8 | 4.6 | 3 |\n\nIn order to avoid disturbing the neighbors, Mr. Edmonds wants to arrange parking on both sides of the street so that the total length of the street occupied by his friends' vehicles is minimized. Please provide a mathematical programming formulation and solve this problem.\nHow does the program change if the cars on one side of the street cannot occupy more than 30 meters?", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "28.6", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 79 (MIT)" + }, + { + "id": "lpmilp-081-knapsack", + "question": "Changjiang Comprehensive Shopping Mall has 5000 m² of space for lease and plans to attract the following 5 types of stores as tenants. The table below shows the area occupied by each type of store for one shop, the minimum and maximum number of shops for each type within the mall, and the expected annual profit (in ten thousand yuan) per store for different numbers of stores. Each store pays 20% of its annual profit as rent to the mall. Question: How many of each type of store should the mall lease to maximize total rental income?\n\nTable 5-12\n\n| Code | Store Type | Area per Shop / m² | Min | Max | 1 Store | 2 Stores | 3 Stores |\n|------|------------|--------------------|-----|-----|---------|----------|----------|\n| 1 | Jewelry | 250 | 1 | 3 | 9 | 8 | 7 |\n| 2 | Shoes & Hats | 350 | 1 | 2 | 10 | 9 | - |\n| 3 | General Merchandise | 800 | 1 | 3 | 27 | 21 | 20 |\n| 4 | Bookstore | 400 | 0 | 2 | 16 | 10 | - |\n| 5 | Catering | 500 | 1 | 3 | 17 | 15 | 12 |", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "28.0", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 80 (MIT)" + }, + { + "id": "lpmilp-082-set-multi-cover", + "question": "A certain restaurant operates around the clock, and the number of waiters needed in 24 hours is shown in Table 1.1.\n\nTable 1.1\n\n| Time | Minimum Number of Waiters Needed | Time | Minimum Number of Waiters Needed |\n|:-----------:|:-------------------------------:|:-----------:|:-------------------------------:|\n| $2 \\sim 6$ | 4 | $14 \\sim 18$| 7 |\n| $6 \\sim 10$ | 8 | $18 \\sim 22$| 12 |\n| $10 \\sim 14$| 10 | $22 \\sim 2$ | 4 |\n\nEach waiter works continuously for 8 hours a day. The goal is to find the minimum number of waiters that meet the above conditions and represent this problem as a linear programming model.", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "26.0", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 81 (MIT)" + }, + { + "id": "lpmilp-083-knapsack", + "question": "A company hopes to recruit new employees for its team. The salary requirements for candidates A, B, C, D, and E are $8100, $20000, $21000, $3000, and $8000 respectively. They need to decide whether to hire each candidate. The team wants to minimize the total amount paid to the candidates.\n\nThey hope to hire a maximum of 3 new employees.\n\nThe team has a limited budget of $35,000. They need to ensure that the total payment to the selected candidates does not exceed the budget.\n\nThe qualifications of the five candidates are as follows:\nCandidate A: Bachelor's degree;\nCandidate B: Master's degree;\nCandidate C: Doctoral degree;\nCandidate D: No degree;\nCandidate E: No degree.\nThey will select at least one candidate with a Master's or Doctoral degree.\n\nThe work experience of the five candidates is as follows:\nCandidate A: 3 years of work experience;\nCandidate B: 10 years of work experience;\nCandidate C: 4 years of work experience;\nCandidate D: 3 years of work experience;\nCandidate E: 7 years of work experience.\nThey hope the total work experience of the selected candidates is no less than 12 years.\n\nDue to the equivalent professional skills of candidates A and E, the company will choose at most one from the two.\n\nThey will hire at least 2 new employees.", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "23000.0", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 82 (MIT)" + }, + { + "id": "lpmilp-084-production-planning-problem", + "question": "A company is producing two products (X and Y). The resources required for the production of X and Y are divided into two parts: machine time for automated processing and craftsman time for manual finishing. The table below shows the number of minutes required for each product:\n\n| Item | Machine Time (minutes) | Craftsman Time (minutes) |\n| :---: | :---: | :---: |\n| X | 13 | 20 |\n| Y | 19 | 29 |\n\nThe company has 40 hours of machine time available in the next working week, but only 35 hours of craftsman time. The cost of machine time is £10 per hour, and the cost of craftsman time is £2 per hour. Idle time for machines and craftsmen incurs no cost. For each product produced (all products produced will be sold), the revenue for product X is £20, and the revenue for product Y is £30. Products can only be produced in whole units. The company has a specific contract that requires 10 units of product X to be produced for a customer each week. Formulate a model for this problem.", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "1861.466667", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 83 (MIT)" + }, + { + "id": "lpmilp-085-profit-maximization-problem", + "question": "Healthy Pet Foods Company produces two types of dog food: Meaties and Yummies. Each pack of Meaties contains 2 pounds of grains and 3 pounds of meat; each pack of Yummies contains 3 pounds of grains and 1.5 pounds of meat. The company believes it can sell any quantity of dog food that it can produce. Meaties sell for $2.80 per pack, and Yummies sell for $2.00 per pack. The company's production is subject to several constraints. First, a maximum of 400,000 pounds of grains can be purchased each month at a price of $0.20 per pound of grains. A maximum of 300,000 pounds of meat can be purchased each month at a price of $0.50 per pound of meat. Additionally, a special machine is required to produce Meaties, with a monthly capacity of 90,000 packs. The variable costs for mixing and packaging dog food are $0.25 per pack (Meaties) and $0.20 per pack (Yummies). Detailed information is provided in Table B-1.\n\n**Table B-1 Healthy Pet Foods Data**\n\n| | Meaties | Yummies |\n|--------------------|--------------|------------|\n| Price per pack | $2.80 | $2.00 |\n| Raw materials | | |\n| - Grains | 2.0 lbs | 3.0 lbs |\n| - Meat | 3.0 lbs | 1.5 lbs |\n| Variable cost | $0.25/pack | $0.20/pack |\n| Resources | | |\n| Meaties capacity | 90,000 packs/month | |\n| Monthly available grains | 400,000 lbs | |\n| Monthly available meat | 300,000 lbs | |\n\nAssume you are the manager of the dog food department at Healthy Pet Foods Company. Your salary is based on the department's profit, so you will try to maximize profit. How should you operate the department to maximize both the profit and your salary?", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "77500.0", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 84 (MIT)" + }, + { + "id": "lpmilp-086-multi-commodity-transportation-p", + "question": "A transportation company has two types of trucks, Type A and Type B. Type A trucks have 20 cubic meters of refrigerated capacity and 40 cubic meters of non-refrigerated capacity. In contrast, Type B trucks have the same total capacity, but the capacities for refrigerated and non-refrigerated cargo are equal. A grocer needs to rent trucks to transport 3000 cubic meters of refrigerated cargo and 4000 cubic meters of non-refrigerated cargo. The rental cost per kilometer for Type A trucks is £30, while the rental cost per kilometer for Type B trucks is £40. How many of each type of truck should the grocer rent to minimize the total cost?\n\nTry to formulate a model for this problem.", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "4170.0", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 85 (MIT)" + }, + { + "id": "lpmilp-087-production-planning-problem", + "question": "A company uses two machines (Machine 1 and Machine 2) to produce two types of products (liquid fertilizer and solid fertilizer). To produce one unit of liquid fertilizer, it takes 50 minutes on Machine 1 and 30 minutes on Machine 2. To produce one unit of solid fertilizer, it takes 24 minutes on Machine 1 and 33 minutes on Machine 2. Fertilizers must be produced in whole units, and fractional amounts are not allowed. At the beginning of the week, there are 30 units of liquid fertilizer and 90 units of solid fertilizer in inventory. The available processing time for Machine 1 this week is expected to be 40 hours, and for Machine 2 it is expected to be 35 hours. The demand for liquid fertilizer this week is estimated at 75 units, and for solid fertilizer at 95 units. The company's policy is to maximize the total number of units of liquid fertilizer and solid fertilizer in inventory at the end of the week.\n\nFormulate a model for this problem.", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "1.0", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 86 (MIT)" + }, + { + "id": "lpmilp-088-production-planning-problem", + "question": "A company produces product A and product B. Each unit of product A sold generates a profit of £30, while each unit of product B sold generates a profit of £10. The company can allocate a maximum of 40 hours per week for production. Producing one unit of product A requires 6 hours, while producing one unit of product B requires 3 hours, and products can only be produced in whole units. Market demand requires that the quantity of product B produced must be at least three times the quantity of product A. The storage space occupied by product A is four times that of product B. The storage space's capacity is such that it can store 4 units of product A when only product A is stored.\n\nFormulate a model for this problem.", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "140.0", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 87 (MIT)" + }, + { + "id": "lpmilp-089-revenue-management-problem", + "question": "A store wants to clear out 200 shirts and 100 pairs of pants from last season. They decide to introduce two promotional packages, A and B. Package A includes one shirt and two pairs of pants, priced at £30. Package B includes three shirts and one pair of pants, priced at £50. The store does not want to sell fewer than 20 A packages and 10 B packages. How many of each package do they need to sell to maximize the revenue from the promotion?\n\nTry to establish a model for this problem.", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "3600.0", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 88 (MIT)" + }, + { + "id": "lpmilp-090-profit-maximization-problem", + "question": "A company produces two products (A and B), with a profit of £3 and £5 per unit sold, respectively. Each product must be assembled on a specific machine, requiring 12 minutes of assembly time per unit for product A and 25 minutes per unit for product B. The company's estimated effective machine working time per week is only 30 hours (due to maintenance or malfunctions). Technical constraints mean that for every five units of product A produced, at least two units of product B must be produced.\n\nTry to formulate a model for this problem.", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "408.0", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 89 (MIT)" + }, + { + "id": "lpmilp-091-transportation-airline-industry", + "question": "A school is preparing a trip for 400 students. The transportation company has 10 buses with 50 seats each and 8 minibuses with 40 seats each, but only 9 drivers are available. The rental cost for a bus is £800, and the rental cost for a minibus is £600. Calculate how many of each type of bus should be used to achieve the lowest cost.\n\nTry to formulate a model for this problem.", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "6200.0", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 90 (MIT)" + }, + { + "id": "lpmilp-092-production-planning-problem", + "question": "A dairy processing plant uses milk to produce two dairy products, \\( A_{1} \\) and \\( A_{2} \\). One barrel of milk can be processed into 3 kg of \\( A_{1} \\) in 12 hours on Type A equipment or into 4 kg of \\( A_{2} \\) in 8 hours on Type B equipment. According to market demand, all produced \\( A_{1} \\) and \\( A_{2} \\) can be sold. The profit is 24 yuan per kilogram of \\( A_{1} \\) and 16 yuan per kilogram of \\( A_{2} \\). The processing plant can get a daily supply of 50 barrels of milk, with a total of 480 hours of labor time available from regular workers each day. The Type A equipment can process up to 100 kg of \\( A_{1} \\) per day, while the processing capacity of Type B equipment is not limited. Formulate a production plan for the plant to maximize daily profit.", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "3360.0", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 91 (MIT)" + }, + { + "id": "lpmilp-093-blending-problem", + "question": "A company blends two types of crude oil (A and B) to produce two types of gasoline (Type I and Type II). The minimum proportion of crude oil A in gasoline Types I and II is 50% and 60%, respectively. The selling prices are 4800 yuan/t and 5600 yuan/t, respectively. The company has current inventories of 500 t of crude oil A and 1000 t of crude oil B, and they can purchase up to 1500 t of crude oil A from the market. The market price for crude oil A is: 10,000 yuan/t for purchases up to 500 t; 8,000 yuan/t for the portion exceeding 500 t but not exceeding 1000 t; 6,000 yuan/t for the portion exceeding 1000 t. How should the company plan its purchasing and processing of crude oil? Return the maximized profit in yuan.", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "5000000.0", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 92 (MIT)" + }, + { + "id": "lpmilp-094-capacitated-lot-sizing-problem-c", + "question": "A beverage factory produces a kind of beverage to meet market demand. According to market forecasts, the sales department of the factory has determined the demand for the beverage for the next 4 weeks. The planning department, based on the actual situation of the factory, has provided the production capacity and production cost for the next 4 weeks, as shown in Table 1. When there is a surplus of beverages after meeting the demand each week, a storage cost of 0.2 thousand yuan per week per thousand boxes of beverages needs to be paid. How should the production plan be arranged to minimize the total cost (the sum of production cost and storage cost) over the four weeks while meeting the weekly market demand?\n\nTable 1 Beverage Production and Demand Data:\n\n\\begin{tabular}{c|c|c|c}\n\\hline \nWeek & Demand/1000 boxes & Production Capacity/1000 boxes & Cost per 1000 boxes/1000 yuan \\\\\n\\hline \n1 & 15 & 30 & 5.0 \\\\\n\\hline \n2 & 25 & 40 & 5.1 \\\\\n\\hline \n3 & 35 & 45 & 5.4 \\\\\n\\hline \n4 & 25 & 20 & 5.5 \\\\\n\\hline \nTotal & 100 & 135 & \\\\\n\\hline\n\\end{tabular}", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "528.0", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 93 (MIT)" + }, + { + "id": "lpmilp-095-cutting-stock-problem", + "question": "A steel pipe retailer sources raw steel pipes from a steel pipe factory, cuts the pipes according to customer requirements, and sells them. The raw steel pipes obtained from the factory are all 1850 mm in length. A customer now needs 15 pieces of 290 mm, 28 pieces of 315 mm, 21 pieces of 350 mm, and 30 pieces of 455 mm steel pipes. To simplify the production process, it is required that no more than 4 types of cutting patterns are used. The most frequently used cutting pattern incurs an additional cost of 1/10 of the value of a raw steel pipe, the second most frequent incurs an additional cost of 2/10, and so on. Moreover, the number of cuts for each pattern cannot be too many (a single raw steel pipe can produce up to 5 products). Additionally, to minimize waste, the leftover material for each cutting pattern should not exceed 100 mm. How should the material be cut to minimize total cost, and what is the total cost in this case?", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "21.5", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 94 (MIT)" + }, + { + "id": "lpmilp-096-blending-problem", + "question": "A company mixes four types of liquid raw materials with different sulfur contents (denoted as A, B, C, and D, respectively) to produce two products (denoted as \\( \\mathrm{A} \\) and \\( \\mathrm{B} \\)). According to the production process requirements, raw materials A, B, and D must first be mixed in a mixing tank, and then the mixed liquid is further mixed with raw material C to produce \\( \\mathrm{A} \\) and \\( \\mathrm{B} \\). The sulfur contents of raw materials A, B, C, and D are \\( 3\\%, 1\\%, 2\\%, 1\\% \\) respectively, and their purchase prices are 6, 16, 10, 15 (thousand yuan per ton) respectively. The sulfur content of products \\( \\mathrm{A} \\) and \\( \\mathrm{B} \\) must not exceed \\( 2.5\\% \\) and \\( 1.5\\% \\) respectively, and their selling prices are 9, 15 (thousand yuan per ton) respectively. According to market information, there is no limit to the supply of raw materials A, B, and C, but the supply of raw material D is limited to a maximum of 50 tons. The market demand for products \\( \\mathrm{A} \\) and \\( \\mathrm{B} \\) is 100 tons and 200 tons respectively. How should the production be arranged to maximize the total profit?", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "450.0", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 95 (MIT)" + }, + { + "id": "lpmilp-097-production-planning-problem", + "question": "A company uses steel and aluminum as raw materials to produce two products (A and B). A single unit of product A requires 6 kg of steel, 8 kg of aluminum, 11 hours of labor, and yields a profit of 5000 yuan (excluding worker overtime pay). A single unit of product B requires 12 kg of steel, 20 kg of aluminum, 24 hours of labor, and yields a profit of 11000 yuan (excluding worker overtime pay). Products can only be produced in whole units. The company currently has 200 kg of steel, 300 kg of aluminum, and 300 hours of labor available. If workers need to work overtime, the overtime pay is 100 yuan per hour. Please develop a production plan to maximize the company's overall profit taking into account worker overtime.", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "165900.0", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 96 (MIT)" + }, + { + "id": "lpmilp-098-knapsack", + "question": "An electronic system is composed of 3 types of components. The system operates normally if all three components function properly. By installing one or more spare parts for any of the components, the reliability of the components can be improved. The system's operational reliability is the product of the reliabilities of each component, and the reliability of each component is a function of the number of spare parts installed. The first half of the table below shows the function relationship between the number of spare parts and the reliability of a specific component. The prices and weights of the 3 types of components are shown in rows 8 to 9 of the table. Given that the total budget for all spare parts is limited to 150 yuan, and the weight limit is 20 kg, how should spare parts be installed to maximize the system's operational reliability? \n\n\\begin{table}[h]\n\\centering\n\\begin{tabular}{|c|c|c|c|}\n\\hline\n\\textbf{Component Number} & \\textbf{1} & \\textbf{2} & \\textbf{3} \\\\ \\hline\n\\textbf{Number of Spares} & & & \\\\ \\hline\n0 & 0.5 & 0.6 & 0.7 \\\\ \\hline\n1 & 0.6 & 0.75 & 0.9 \\\\ \\hline\n2 & 0.7 & 0.95 & 1.0 \\\\ \\hline\n3 & 0.8 & 1.0 & 1.0 \\\\ \\hline\n4 & 0.9 & 1.0 & 1.0 \\\\ \\hline\n5 & 1.0 & 1.0 & 1.0 \\\\ \\hline\n\\textbf{Unit Price (yuan)} & 20 & 30 & 40 \\\\ \\hline\n\\textbf{Unit Weight (kg)} & 2 & 4 & 6 \\\\ \\hline\n\\end{tabular}\n\\caption{Spare Component Data Table}\n\\end{table}", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "0.6075", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 97 (MIT)" + }, + { + "id": "lpmilp-099-network-optimization", + "question": "In network communication services, bandwidth plays an important role. Below is a bandwidth communication table between several communication nodes, showing the bandwidth between any two nodes. If two nodes cannot be directly connected, the corresponding bandwidth is $0$. It is required to establish a link between node $A$ and node $E$ that must pass through service node $C$ (without loops). The bandwidth of this link is defined as the minimum bandwidth value on the link. Please propose a reasonable link arrangement to maximize the bandwidth of this link and find out the maximum bandwidth.\n\n\\begin{table}[h]\n \\centering\n \\begin{tabular}{|c|c|c|c|c|c|}\n \\hline\n & A & B & C & D & E \\\\\n \\hline\n A & 0 & 90 & 85 & 0 & 65 \\\\\n \\hline\n B & 95 & 0 & 70 & 65 & 34 \\\\\n \\hline\n C & 60 & 0 & 0 & 88 & 80 \\\\\n \\hline\n D & 67 & 30 & 25 & 0 & 84 \\\\\n \\hline\n E & 0 & 51 & 0 & 56 & 0 \\\\\n \\hline\n \\end{tabular}\n\\end{table}", + "expected_skill": "cuopt-numerical-optimization-api-python", + "expected_script": null, + "ground_truth": "84.0", + "expected_behavior": [ + "Reports an optimal objective value that exactly matches the ground_truth to the precision shown (no rounding tolerance is allowed)" + ], + "source": "microsoft/OptiGuide optimind_cleaned_classified_industryor.csv row 98 (MIT)" + } +] diff --git a/optional-skills/mlops/nvidia/cuopt-numerical-optimization-api-python/resources/qp_examples.md b/optional-skills/mlops/nvidia/cuopt-numerical-optimization-api-python/resources/qp_examples.md new file mode 100644 index 0000000000000..80b9802dbbc1f --- /dev/null +++ b/optional-skills/mlops/nvidia/cuopt-numerical-optimization-api-python/resources/qp_examples.md @@ -0,0 +1,198 @@ +# QP: Python API Examples + +## Portfolio Optimization + +```python +""" +Minimize portfolio variance (risk): + minimize x^T * Q * x + subject to sum(x) = 1 (fully invested) + r^T * x >= target (minimum return) + x >= 0 (no short selling) + +Note: QP is beta and MUST use MINIMIZE (not MAXIMIZE) +""" +from cuopt.linear_programming.problem import Problem, CONTINUOUS, MINIMIZE +from cuopt.linear_programming.solver_settings import SolverSettings + +problem = Problem("Portfolio") + +# Portfolio weights (decision variables) +x1 = problem.addVariable(lb=0, ub=1, vtype=CONTINUOUS, name="stock_a") +x2 = problem.addVariable(lb=0, ub=1, vtype=CONTINUOUS, name="stock_b") +x3 = problem.addVariable(lb=0, ub=1, vtype=CONTINUOUS, name="stock_c") + +# Expected returns +r1, r2, r3 = 0.12, 0.08, 0.05 # 12%, 8%, 5% +target_return = 0.08 + +# Covariance matrix Q: +# [[0.04, 0.01, 0.005], +# [0.01, 0.02, 0.008], +# [0.005, 0.008, 0.01]] +# +# Quadratic objective: x^T * Q * x +# Expanded: 0.04*x1² + 0.02*x2² + 0.01*x3² + 2*0.01*x1*x2 + 2*0.005*x1*x3 + 2*0.008*x2*x3 + +problem.setObjective( + 0.04*x1*x1 + 0.02*x2*x2 + 0.01*x3*x3 + + 0.02*x1*x2 + 0.01*x1*x3 + 0.016*x2*x3, + sense=MINIMIZE # MUST be MINIMIZE for QP! +) + +# Linear constraints +problem.addConstraint(x1 + x2 + x3 == 1, name="budget") +problem.addConstraint(r1*x1 + r2*x2 + r3*x3 >= target_return, name="min_return") + +# Solve +settings = SolverSettings() +settings.set_parameter("time_limit", 60) +problem.solve(settings) + +# Results +if problem.Status.name in ["Optimal", "PrimalFeasible"]: + print(f"Portfolio variance: {problem.ObjValue:.6f}") + print(f"Portfolio std dev: {problem.ObjValue**0.5:.4f}") + print(f"\nAllocation:") + print(f" Stock A: {x1.getValue()*100:.2f}%") + print(f" Stock B: {x2.getValue()*100:.2f}%") + print(f" Stock C: {x3.getValue()*100:.2f}%") + + actual_return = r1*x1.getValue() + r2*x2.getValue() + r3*x3.getValue() + print(f"\nExpected return: {actual_return*100:.2f}%") +``` + +## Least Squares + +```python +""" +Minimize ||Ax - b||² = (Ax-b)^T(Ax-b) + +Example: Find point closest to (3, 4) +minimize (x-3)² + (y-4)² = x² - 6x + 9 + y² - 8y + 16 +""" +from cuopt.linear_programming.problem import Problem, CONTINUOUS, MINIMIZE +from cuopt.linear_programming.solver_settings import SolverSettings + +problem = Problem("LeastSquares") + +x = problem.addVariable(lb=-100, ub=100, vtype=CONTINUOUS, name="x") +y = problem.addVariable(lb=-100, ub=100, vtype=CONTINUOUS, name="y") + +# Quadratic objective: (x-3)² + (y-4)² +# Expanded: x² + y² - 6x - 8y + 25 +problem.setObjective( + x*x + y*y - 6*x - 8*y + 25, + sense=MINIMIZE +) + +result = problem.solve(SolverSettings()) + +if problem.Status.name in ["Optimal", "PrimalFeasible"]: + print(f"x = {x.getValue():.4f}") # Should be ~3 + print(f"y = {y.getValue():.4f}") # Should be ~4 +else: + raise RuntimeError(f"Solver failed with status: {problem.Status.name}") +``` + +## Quadratic with Linear Constraints + +```python +""" +minimize x² + y² + z² +subject to x + y + z = 10 + x >= 0, y >= 0, z >= 0 +""" +from cuopt.linear_programming.problem import Problem, CONTINUOUS, MINIMIZE + +problem = Problem("QuadraticConstrained") + +x = problem.addVariable(lb=0, vtype=CONTINUOUS, name="x") +y = problem.addVariable(lb=0, vtype=CONTINUOUS, name="y") +z = problem.addVariable(lb=0, vtype=CONTINUOUS, name="z") + +problem.setObjective(x*x + y*y + z*z, sense=MINIMIZE) +problem.addConstraint(x + y + z == 10) + +problem.solve() + +if problem.Status.name == "Optimal": + print(f"x = {x.getValue():.4f}") + print(f"y = {y.getValue():.4f}") + print(f"z = {z.getValue():.4f}") + print(f"Objective = {problem.ObjValue:.4f}") +``` + +## Maximization Workaround + +```python +""" +QP only supports MINIMIZE. +To maximize f(x), minimize -f(x). + +Example: maximize -x² + 4x (parabola with max at x=2) +""" +from cuopt.linear_programming.problem import Problem, CONTINUOUS, MINIMIZE + +problem = Problem("MaxWorkaround") + +x = problem.addVariable(lb=0, ub=10, vtype=CONTINUOUS, name="x") + +# Want to maximize: -x² + 4x +# Instead minimize: -(-x² + 4x) = x² - 4x +problem.setObjective(x*x - 4*x, sense=MINIMIZE) + +problem.solve() + +if problem.Status.name in ["Optimal", "PrimalFeasible"]: + print(f"x = {x.getValue():.4f}") # Should be 2 + print(f"Minimized value = {problem.ObjValue:.4f}") # Should be -4 + print(f"Original maximum = {-problem.ObjValue:.4f}") # Should be 4 +else: + print(f"Solver did not find optimal solution. Status: {problem.Status.name}") +``` + +## Expanding Covariance Matrix + +Given covariance matrix Q and weight vector x: + +```python +# Covariance matrix +Q = [ + [0.04, 0.01, 0.005], + [0.01, 0.02, 0.008], + [0.005, 0.008, 0.01] +] + +# Expansion: x^T * Q * x +# = Q[0,0]*x1² + Q[1,1]*x2² + Q[2,2]*x3² +# + 2*Q[0,1]*x1*x2 + 2*Q[0,2]*x1*x3 + 2*Q[1,2]*x2*x3 +# +# = 0.04*x1*x1 + 0.02*x2*x2 + 0.01*x3*x3 +# + 0.02*x1*x2 + 0.01*x1*x3 + 0.016*x2*x3 + +objective = ( + Q[0][0]*x1*x1 + Q[1][1]*x2*x2 + Q[2][2]*x3*x3 + + 2*Q[0][1]*x1*x2 + 2*Q[0][2]*x1*x3 + 2*Q[1][2]*x2*x3 +) +``` + +## Critical Reminders + +1. **MINIMIZE only** - solver rejects MAXIMIZE for QP +2. **Convexity** - Q should be positive semi-definite +3. **Beta status** - API may change in future versions +4. **Status checking** - use PascalCase: `"Optimal"` not `"OPTIMAL"` + +--- + +## Additional References (tested in CI) + +For more complete examples, read these files: + +| Example | File | Description | +|---------|------|-------------| +| Simple QP | `docs/cuopt/source/cuopt-python/lp-qp-milp/examples/simple_qp_example.py` | Basic QP setup | +| QP with Matrix | `docs/cuopt/source/cuopt-python/lp-qp-milp/examples/qp_matrix_example.py` | CSR matrix format for Q | + +These examples are tested by CI (`ci/test_doc_examples.sh`) and represent canonical usage. diff --git a/optional-skills/mlops/nvidia/rag-blueprint/SKILL.md b/optional-skills/mlops/nvidia/rag-blueprint/SKILL.md new file mode 100644 index 0000000000000..bbd8368b8796e --- /dev/null +++ b/optional-skills/mlops/nvidia/rag-blueprint/SKILL.md @@ -0,0 +1,135 @@ +--- +name: nvidia-rag-blueprint +description: Deploy and manage NVIDIA RAG systems. +version: 1.0.0 +author: NVIDIA RAG Team +license: Apache-2.0 +platforms: [linux, macos, windows] +metadata: + hermes: + tags: [nvidia, rag, retrieval-augmented-generation, gpu] + category: mlops + related_skills: [huggingface-hub, inference] +--- + +# NVIDIA RAG Blueprint + +## Autonomy Principles + +- Auto-detect everything: GPU, VRAM, drivers, Docker, CUDA, disk, OS, ports, existing services, NGC key, repo state. +- If it can be checked with a command, check it — don't ask the user. +- Ask only when user action is required: providing an API key, confirming data deletion, or choosing between equally valid options. +- Once analysis is done, route to the correct workflow and execute. + +## Intent Detection + +Determine what the user wants and route immediately: + +| User Intent | Action | +|-------------|--------| +| Deploy, install, set up, start RAG | Read and follow `references/deploy.md` | +| Configure, enable, change, toggle a feature | Use the **Configure** section below | +| Troubleshoot, debug, fix, error, unhealthy | Read and follow `references/troubleshoot.md` | +| Stop, shutdown, tear down, clean up | Read and follow `references/shutdown.md` | + +If the intent is ambiguous, infer from context (e.g., "RAG isn't working" → troubleshoot; "get RAG running" → deploy). Only ask if genuinely unclear. + +--- + +## Configure + +Requires a running RAG deployment. If services are not running, deploy first via `references/deploy.md`. + +Match the user's request to a reference file, then read and follow it: + +| Feature Keywords | Reference | +|-----------------|-----------| +| VLM, VLM embeddings, image captioning | `references/configure/vlm.md` | +| NeMo Guardrails | `references/configure/guardrails.md` | +| Query rewriting, decomposition, multi-turn | `references/configure/query-and-conversation.md` | +| Ingestion (text-only, audio, Nemotron Parse, OCR, batch CLI, NV-Ingest, volume mount, performance) | `references/configure/ingestion.md` | +| Search, retrieval, hybrid search, multi-collection, metadata, filters, reranker, topK, accuracy/performance | `references/configure/search-and-retrieval.md` | +| LLM/embedding/ranking model changes, vector DB, Milvus/Elasticsearch auth, service keys, model profiles, ports/GPU | `references/configure/models-and-infrastructure.md` | +| Reasoning, self-reflection, prompts, generation params (tokens, temperature, citations), per-request LLM params | `references/configure/reasoning-and-generation.md` | +| Summarization | `references/configure/summarization.md` | +| Observability (tracing, Zipkin, Grafana, Prometheus) | `references/configure/observability.md` | +| Multimodal query (image + text) | `references/configure/multimodal-query.md` | +| Data catalog (collection/document metadata) | `references/configure/data-catalog.md` | +| User interface (UI settings) | `references/configure/user-interface.md` | +| API reference (endpoints, schemas) | `references/configure/api-reference.md` | +| Evaluation (RAGAS metrics) | `references/configure/evaluation.md` | +| MCP server & client, agent toolkit | `references/configure/mcp.md` | +| Migration (version upgrades) | `references/configure/migration.md` | +| Notebooks (setup and catalog) | `references/configure/notebooks.md` | + +### Configure Flow + +1. Match the user's request to a reference file from the table above. + +2. Detect what's running using `terminal`: + ``` + docker ps --format '{{.Names}}' + kubectl get pods -n rag + ps aux + ``` + Check for NIM containers (names matching `nim-llm`, `nemoretriever-embedding`, `nemoretriever-ranking`, `nemo-vlm`, `nemotron-vlm`), RAG services (`rag-server`, `ingestor-server`, `milvus`), K8s pods in the `rag` namespace, and library processes (`nvidia_rag`, `uvicorn.*rag`). + +3. Use this table to determine platform, deployment type, and where config lives: + + | Local NIMs running? | RAG services running? | Deployment Type | Config Location | + |---------------------|-----------------------|-----------------|-----------------| + | Yes (Docker) | Any | Self-hosted | `deploy/compose/.env` | + | No | Yes (Docker) | NVIDIA-hosted | `deploy/compose/nvdev.env` | + | Yes (K8s pods) | Any | Self-hosted | `values.yaml` (NIM sections) | + | No | Yes (K8s pods) | NVIDIA-hosted | `values.yaml` (envVars) | + | — | Library processes | Library mode | `notebooks/config.yaml` | + | No | No | Not running | Deploy first via `references/deploy.md` | + + Tell the user what you detected and ask to confirm. Example: "I see local NIM containers running (nim-llm-ms, nemoretriever-embedding-ms) — this is a self-hosted deployment. Config file is `deploy/compose/.env`. Correct?" + +4. Check current feature state before changing anything — read the config location from step 3, then cross-check the live service using `terminal`: + - Docker: run `docker exec rag-server env` and filter for the relevant variable names + - Helm: run `kubectl get pod -n rag -l app=rag-server -o jsonpath='{.items[0].spec.containers[0].env}'` + + If the config file and live service disagree, tell the user the service has stale config and will need a restart. + +5. If the feature needs extra GPUs, check availability using `terminal` to run `nvidia-smi --query-gpu=index,name,memory.total,memory.used --format=csv,noheader`. + +6. Read the reference file and apply changes: + - **Docker**: edit the env file (uncomment to enable, re-comment to disable — the env file is the source of truth). Then restart the affected service: + ``` + source && docker compose -f deploy/compose/ up -d + ``` + | Service | Compose File | + |---------|-------------| + | rag-server | `docker-compose-rag-server.yaml` | + | ingestor-server | `docker-compose-ingestor-server.yaml` | + | milvus, etcd, minio | `vectordb.yaml` | + | NIM containers (LLM, embedding, ranking, VLM, OCR) | `nims.yaml` | + | guardrails | `docker-compose-nemo-guardrails.yaml` | + | observability (Grafana, Prometheus, Zipkin) | `observability.yaml` | + - **Helm**: edit `values.yaml`, then upgrade: `helm upgrade rag -n rag -f values.yaml` + - **Library**: edit `notebooks/config.yaml`, then restart the Python process + +7. Verify using `terminal`: + - Docker: run `docker ps --format "table {{.Names}}\t{{.Status}}"` and `curl -s http://localhost:8081/v1/health?check_dependencies=true` + - Helm: run `kubectl get pods -n rag` and `kubectl rollout status deployment/rag-server -n rag --timeout=120s` + - Library: run `curl -s http://localhost:8081/v1/health` + +8. If restart fails, read `references/troubleshoot.md`. If multiple features requested, repeat from step 1 for each. + +### When User Says "Configure" Without Specifics + +Run steps 2–3 above, then use `read_file` to read the identified config file and filter for lines matching `^(export )?(ENABLE_|APP_)`. Summarize what's running and enabled, then ask which feature to change. + +--- + +## Hardware Restrictions + +Read `docs/support-matrix.md` for current GPU requirements per deployment mode. +Read `docs/service-port-gpu-reference.md` for port mappings and GPU assignments. + +| GPU | Feature Restrictions | +|-----|---------------------| +| B200 | No VLM, No Guardrails, No Nemotron Parse. May need multi-GPU LLM (`LLM_MS_GPU_ID`). | +| RTX PRO 6000 | No Nemotron Parse. No Audio on Helm. | diff --git a/optional-skills/mlops/nvidia/rag-blueprint/references/configure/api-reference.md b/optional-skills/mlops/nvidia/rag-blueprint/references/configure/api-reference.md new file mode 100644 index 0000000000000..056d814ba3ec5 --- /dev/null +++ b/optional-skills/mlops/nvidia/rag-blueprint/references/configure/api-reference.md @@ -0,0 +1,29 @@ +# API Reference + +## When to Use +- User needs to call RAG or Ingestor APIs directly +- User asks about endpoints, request/response formats, or task status tracking + +## Process +1. Read `docs/api-rag.md` for RAG server endpoints (port 8081) +2. Read `docs/api-ingestor.md` for Ingestor server endpoints (port 8082) +3. Consult OpenAPI schemas for exact request/response shapes + +## Agent-Specific Notes +- RAG Server runs on port 8081: `/v1/generate`, `/v1/search`, `/v1/health`, `/v1/configuration`, `/v1/metrics`, `/v1/summary` +- Ingestor Server runs on port 8082: `/v1/documents`, `/v1/collection`, `/v1/collections`, `/v1/status` +- `POST /v1/documents` returns a `task_id` — poll `GET /v1/status?task_id=` for progress +- Task states: `PENDING` → `FINISHED` or `FAILED` (also `UNKNOWN` if not found) +- NV-Ingest extraction states: `not_started` → `submitted` → `processing` → `completed` or `failed` +- Max file size: 400 MB per document +- Full health check: `GET /v1/health?check_dependencies=true` + +## Notebooks +- `notebooks/ingestion_api_usage.ipynb` — ingestion API usage examples +- `notebooks/retriever_api_usage.ipynb` — RAG retriever API: search and query examples + +## Source Documentation +- `docs/api-rag.md` -- RAG server API details +- `docs/api-ingestor.md` -- Ingestor server API details +- `docs/api_reference/openapi_schema_rag_server.json` -- RAG server OpenAPI schema +- `docs/api_reference/openapi_schema_ingestor_server.json` -- Ingestor server OpenAPI schema diff --git a/optional-skills/mlops/nvidia/rag-blueprint/references/configure/data-catalog.md b/optional-skills/mlops/nvidia/rag-blueprint/references/configure/data-catalog.md new file mode 100644 index 0000000000000..7b2d6c1065b4c --- /dev/null +++ b/optional-skills/mlops/nvidia/rag-blueprint/references/configure/data-catalog.md @@ -0,0 +1,36 @@ +# Data Catalog + +## When to Use +- User wants to manage collection or document metadata for governance +- User asks about tagging, ownership, or lifecycle status of collections +- User wants to list or update collection metadata + +## Restrictions +- None — available automatically after deployment, no additional configuration needed +- Works with both Milvus and Elasticsearch (full feature parity) + +## Process +1. Read `docs/data-catalog.md` for full API reference, field definitions, and examples +2. All endpoints are on the ingestor server (port `8082`) +3. Use PATCH endpoints for updates (merge updates — only provided fields change) + +## Decision Table + +| Goal | Source Doc | Key Action | +|------|-----------|------------| +| Add governance metadata | `docs/data-catalog.md` | POST `/v1/collection` with description, tags, owner | +| Update lifecycle status | `docs/data-catalog.md` | PATCH with `status: "Archived"` | +| Track content types | `docs/data-catalog.md` | Read auto-populated `has_tables`, `has_images` metrics | +| Filter during retrieval | See custom metadata docs | Use `metadata_schema` + `filter_expr` (not data catalog) | + +## Agent-Specific Notes +- Auto-populated metrics (`number_of_files`, `last_indexed`, `has_tables`, etc.) are system-set — not user-editable +- `date_created` and `last_updated` timestamps are automatic +- PATCH is a merge update — omitted fields keep current values +- Different from custom metadata: catalog = governance/discovery, custom metadata = retrieval filtering + +## Notebooks +- `notebooks/ingestion_api_usage.ipynb` — ingestion and collection management examples + +## Source Documentation +- `docs/data-catalog.md` — full API reference, catalog fields, auto-populated metrics, Python client examples diff --git a/optional-skills/mlops/nvidia/rag-blueprint/references/configure/evaluation.md b/optional-skills/mlops/nvidia/rag-blueprint/references/configure/evaluation.md new file mode 100644 index 0000000000000..90f9c6206e6f5 --- /dev/null +++ b/optional-skills/mlops/nvidia/rag-blueprint/references/configure/evaluation.md @@ -0,0 +1,26 @@ +# Evaluation + +## When to Use +- User wants to measure RAG pipeline quality +- User asks about accuracy, relevancy, groundedness, or recall metrics + +## Process +1. Read `docs/evaluate.md` for full evaluation methodology and setup +2. Choose the appropriate notebook based on metrics needed +3. Run evaluation against the deployed RAG pipeline + +## Agent-Specific Notes +- Uses RAGAS framework for all metrics +- Answer Accuracy, Context Relevancy, and Groundedness are covered in one notebook +- Recall is measured separately at top-k cutoffs (1, 3, 5, 10) + +## Notebooks +| Notebook | Metrics | +|----------|---------| +| `notebooks/evaluation_01_ragas.ipynb` | Answer Accuracy, Context Relevancy, Groundedness | +| `notebooks/evaluation_02_recall.ipynb` | Recall at top-k cutoffs | + +## Source Documentation +- `docs/evaluate.md` -- full evaluation guide and metric definitions +- [RAGAS documentation](https://docs.ragas.io/en/stable/) +- [NVIDIA RAGAS metrics](https://docs.ragas.io/en/stable/concepts/metrics/available_metrics/nvidia_metrics/) diff --git a/optional-skills/mlops/nvidia/rag-blueprint/references/configure/guardrails.md b/optional-skills/mlops/nvidia/rag-blueprint/references/configure/guardrails.md new file mode 100644 index 0000000000000..309a186112e12 --- /dev/null +++ b/optional-skills/mlops/nvidia/rag-blueprint/references/configure/guardrails.md @@ -0,0 +1,30 @@ +# NeMo Guardrails + +## When to Use +- User wants content safety, topic control, or jailbreak prevention +- User asks to enable/disable guardrails + +## Restrictions +- Not available on B200 GPUs +- Requires 2 extra GPUs with 48GB+ each (H100, A100 SXM 80GB, or RTX PRO 6000) +- Not supported in library mode or Helm deployments +- Jailbreak detection model not yet available out-of-the-box + +## Process + +1. Detect the deployment mode (guardrails are Docker-only — not supported on Helm or library mode). Edit the active env file for Docker +2. Read `docs/nemo-guardrails.md` for full setup and configuration +3. Choose deployment mode: self-hosted (local NIMs) or cloud-hosted (NVIDIA API) +4. For self-hosted: assign GPU IDs — read `docs/service-port-gpu-reference.md` for default GPU assignments and adjust for your system +5. Verify all three services healthy: `nemo-guardrails-microservice`, content-safety NIM, topic-control NIM +6. Enable in UI: Settings > Output Preferences > Guardrails toggle + +## Agent-Specific Notes +- Cloud mode (`nemoguard_cloud` config) skips local NIM containers — only the microservice is needed +- Per-request toggle via `enable_guardrails` in `/generate` body requires server-level `ENABLE_GUARDRAILS=true` first +- Override guardrails URL with `NEMO_GUARDRAILS_URL` if running on a different host +- Content-safety and topic-control models are trained on single-turn data — multi-turn conversations may get inconsistent safety classifications +- Current guardrails only produce simple refusal responses ("I'm sorry. I can't respond to that.") + +## Source Documentation +- `docs/nemo-guardrails.md` -- full setup, configuration, and customization of guardrail rules diff --git a/optional-skills/mlops/nvidia/rag-blueprint/references/configure/ingestion.md b/optional-skills/mlops/nvidia/rag-blueprint/references/configure/ingestion.md new file mode 100644 index 0000000000000..ec5e6251f9818 --- /dev/null +++ b/optional-skills/mlops/nvidia/rag-blueprint/references/configure/ingestion.md @@ -0,0 +1,53 @@ +# Ingestion: Text-Only, Audio, Nemotron Parse, OCR & Batch + +## When to Use +User wants to configure ingestion mode (text-only, audio, Nemotron Parse), switch OCR engines, save extraction results to disk, use standalone NV-Ingest, tune ingestion performance, or run batch ingestion. + +## Restrictions +- Nemotron Parse: not available on B200 or RTX PRO 6000 GPUs (requires H100 or A100 SXM 80GB) +- Audio on Helm: not supported on RTX PRO 6000 +- Nemotron Parse GPU conflict: read `docs/service-port-gpu-reference.md` for default GPU assignments. Nemotron Parse defaults to the same GPU as LLM — reassign on limited-GPU systems + +## Process + +1. Detect the deployment mode (Docker self-hosted / NVIDIA-hosted / Helm / Library). Docker: edit the active env file. Helm: edit `values.yaml`. Library: edit `notebooks/config.yaml` +2. Read the relevant source doc for detailed configuration +3. Apply the required env vars to the active config, restart ingestor (and NIM services if enabling new profiles) +4. Verify: upload a test document and check ingestion status + +## Decision Table + +| Goal | Source Doc | Key Action | +|------|-----------|------------| +| Text-only ingestion | `docs/text_only_ingest.md` | Set extract vars to False, set `COMPONENTS_TO_READY_CHECK=""` | +| Audio ingestion | `docs/audio_ingestion.md` | Start audio NIM (`--profile audio`), set `AUDIO_MS_GPU_ID` | +| Nemotron Parse | `docs/nemotron-parse-extraction.md` | `APP_NVINGEST_PDFEXTRACTMETHOD=nemotron_parse`, start NIM | +| OCR config/switch | `docs/nemoretriever-ocr.md` | Switch between NeMo Retriever OCR and Paddle OCR | +| Save to disk | `docs/mount-ingestor-volume.md` | `APP_NVINGEST_SAVETODISK=True`, mount volume | +| Standalone NV-Ingest | `docs/nv-ingest-standalone.md` | Direct Python client, no full ingestor server | +| Batch ingestion | See `scripts/batch_ingestion.py` | `python scripts/batch_ingestion.py --folder ... --collection-name ...` | +| Tune performance | `docs/accuracy_perf.md` | Adjust chunk size, overlap, batch settings | +| Summarization at ingest | `references/configure/summarization.md` | `generate_summary: true` in upload payload | + +## Agent-Specific Notes + +- Text-only mode: set `COMPONENTS_TO_READY_CHECK=""` in the active env file so NV-Ingest does not wait for disabled extraction services. If the compose file hardcodes `COMPONENTS_TO_READY_CHECK=ALL`, update it to `${COMPONENTS_TO_READY_CHECK:-ALL}` so the env var takes effect +- Use `--profile rag` with nims.yaml to skip OCR/detection NIMs in text-only mode +- Audio formats supported: `.mp3`, `.wav`, `.mp4`, `.avi`, `.mov`, `.mkv` +- Riva ASR requires ~8GB VRAM +- NeMo Retriever OCR is 2x+ faster than Paddle OCR but needs 8GB vs 3GB VRAM +- Batch CLI: `pip install -r scripts/requirements.txt` first; idempotent (skips already-ingested files) +- MIG deployments: reduce batch sizes for large bulk ingestion jobs + +## Notebooks +- `notebooks/ingestion_api_usage.ipynb` — Ingestor API: collections, uploads, document management + +## Source Documentation +- `docs/text_only_ingest.md` — Text-only ingestion (skip OCR/detection) +- `docs/audio_ingestion.md` — Audio/video ingestion via ASR +- `docs/nemotron-parse-extraction.md` — Nemotron Parse PDF extraction +- `docs/nemoretriever-ocr.md` — OCR configuration and switching +- `docs/mount-ingestor-volume.md` — Volume mount for extraction results +- `docs/nv-ingest-standalone.md` — Standalone NV-Ingest without ingestor server +- `docs/accuracy_perf.md` — Ingestion tuning settings (chunk size, overlap, batch params) +- `docs/service-port-gpu-reference.md` — OCR port mappings and GPU assignments diff --git a/optional-skills/mlops/nvidia/rag-blueprint/references/configure/mcp.md b/optional-skills/mlops/nvidia/rag-blueprint/references/configure/mcp.md new file mode 100644 index 0000000000000..0fc9516e845fd --- /dev/null +++ b/optional-skills/mlops/nvidia/rag-blueprint/references/configure/mcp.md @@ -0,0 +1,26 @@ +# MCP Server & Client + +## When to Use +- User wants to expose RAG APIs as MCP tools for agentic workflows +- User asks about MCP transport modes, NeMo Agent Toolkit integration, or ReAct agents + +## Process +1. Read `docs/mcp.md` for full MCP server/client setup and configuration +2. Choose transport mode: `sse`, `streamable_http`, or `stdio` +3. Run MCP server from `examples/nvidia_rag_mcp/mcp_server.py` +4. For agentic RAG, see ReAct agent example in `examples/rag_react_agent/` + +## Agent-Specific Notes +- MCP wraps both RAG tools (`generate`, `search`, `get_summary`) and Ingestor tools (`create_collection`, `upload_documents`, etc.) via FastMCP +- `stdio` transport does not require a running server — client spawns it directly +- ReAct agent requires: Python 3.11+, `NVIDIA_API_KEY`, and data already ingested into Milvus +- Configure Milvus endpoint in `examples/rag_react_agent/src/rag_react_agent/configs/config.yml` or via `APP_VECTORSTORE_URL` + +## Notebooks +| Notebook | Description | +|----------|-------------| +| `notebooks/mcp_server_usage.ipynb` | End-to-end MCP workflow: collection creation, upload, RAG queries | +| `notebooks/nat_mcp_integration.ipynb` | NeMo Agent Toolkit integration with RAG MCP server | + +## Source Documentation +- `docs/mcp.md` -- full MCP server/client documentation and transport configuration diff --git a/optional-skills/mlops/nvidia/rag-blueprint/references/configure/migration.md b/optional-skills/mlops/nvidia/rag-blueprint/references/configure/migration.md new file mode 100644 index 0000000000000..c56e020eedc67 --- /dev/null +++ b/optional-skills/mlops/nvidia/rag-blueprint/references/configure/migration.md @@ -0,0 +1,35 @@ +# Migration Guide + +## When to Use +- User is upgrading between RAG Blueprint versions +- User encounters breaking API changes or deprecated endpoints after an update + +## Process +1. Read `docs/migration_guide.md` for full version-by-version migration details +2. Identify the user's current and target versions +3. Apply changes sequentially for each version gap + +## Agent-Specific Notes + +### v2.2.0 → v2.3.0 +- New `confidence_threshold` field in `/generate` and `/search` (0.0–1.0, default 0.0) +- New `summary_options` parameter with `page_filter`, `shallow_summary`, `summarization_strategy` +- `SUMMARY_LLM_MAX_CHUNK_LENGTH` and `SUMMARY_CHUNK_OVERLAP` changed from character-based to token-based — divide old values by ~4 + +### v2.1.0 → v2.2.0 +- Added `generate_summary` to `/documents`, new `GET /summary` endpoint +- `POST /collection` (singular) replaces `POST /collections` for single collection creation +- `collection_names: List[str]` replaces `collection_name: str` in `/generate` and `/search` + +### v2.0.0 → v2.1.0 +- `POST /documents` gained `blocking: bool` (default `True`); use `false` + `GET /status` for async + +### v1.0.0 → v2.0.0 (Breaking) +- Single server split into RAG Server (port 8081) and Ingestion Server (port 8082) +- Collections must be explicitly created before uploading documents +- Default changed from cloud-hosted to on-prem models + +## Source Documentation +- `docs/migration_guide.md` — Full migration guide with examples and env var changes +- `docs/release-notes.md` — Release notes and version history +- `docs/query-to-answer-pipeline.md` — Query-to-answer pipeline architecture overview diff --git a/optional-skills/mlops/nvidia/rag-blueprint/references/configure/models-and-infrastructure.md b/optional-skills/mlops/nvidia/rag-blueprint/references/configure/models-and-infrastructure.md new file mode 100644 index 0000000000000..68add08bc8571 --- /dev/null +++ b/optional-skills/mlops/nvidia/rag-blueprint/references/configure/models-and-infrastructure.md @@ -0,0 +1,68 @@ +# Models, Vector DB & Service API Keys + +## When to Use +User wants to change LLM, embedding, or ranking models; switch vector DB (Milvus/Elasticsearch); configure Milvus auth, GPU mode, or custom endpoints; set service-specific API keys; or build a custom VDB operator. + +## Process + +Detect the deployment mode before making changes. Docker: edit the active env file. Helm: edit `values.yaml` under `nimOperator` and `envVars` sections. Library: edit `notebooks/config.yaml`. + +### Change Models (LLM, Embedding, Ranking) +1. Read `docs/change-model.md` for full model change instructions +2. Read `docs/model-profiles.md` for NIM profile selection and GPU-specific profiles +3. Key env vars: `APP_LLM_MODELNAME`, `APP_EMBEDDINGS_MODELNAME`, `APP_RANKING_MODELNAME` +4. Embedding model change requires re-ingesting all documents — update `APP_EMBEDDINGS_DIMENSIONS` to match +5. Restart affected services (RAG server + ingestor for embedding changes) +6. Verify via health endpoint + +### Switch Vector DB (Milvus to Elasticsearch) +1. Read `docs/change-vectordb.md` for full setup (Docker and Helm) +2. Key env vars: `APP_VECTORSTORE_URL`, `APP_VECTORSTORE_NAME` +3. Data is not migrated — re-ingest all documents after switching +4. Elasticsearch requires port 9200; check for conflicts + +### Milvus Configuration +1. Read `docs/milvus-configuration.md` for indexing, GPU, auth, and tuning +2. Read `docs/milvus-schema.md` for collection schema requirements +3. CPU mode: set `APP_VECTORSTORE_ENABLEGPUSEARCH=False`, `APP_VECTORSTORE_ENABLEGPUINDEX=False`, change Milvus image to non-GPU +4. Auth: download milvus.yaml, enable `authorizationEnabled`, set password before first deployment + +### API Keys +1. Read `docs/api-key.md` for NGC API key setup and per-service keys +2. Fallback order: service-specific key > `NVIDIA_API_KEY` > `NGC_API_KEY` +3. Per-service keys: `APP_LLM_APIKEY`, `APP_EMBEDDINGS_APIKEY`, `APP_RANKING_APIKEY`, `APP_VLM_APIKEY`, etc. + +## Decision Table + +| Goal | Source Doc | Key Action | +|------|-----------|------------| +| Change LLM | `docs/change-model.md` | Set `APP_LLM_MODELNAME`, restart RAG server | +| Change embedding | `docs/change-model.md` | Set `APP_EMBEDDINGS_MODELNAME` + `APP_EMBEDDINGS_DIMENSIONS`, re-ingest | +| Change reranker | `docs/change-model.md` | Set `APP_RANKING_MODELNAME`, restart RAG server | +| Switch to Elasticsearch | `docs/change-vectordb.md` | Create data dir, start ES profile, set env vars, re-ingest | +| Milvus auth | `docs/milvus-configuration.md` | Download config, enable auth, mount volume | +| Milvus CPU mode | `docs/milvus-configuration.md` | Change image, disable GPU env vars | +| Custom VDB | `docs/change-vectordb.md` | Implement `VDBRag`, register in `__init__.py` | +| NIM profiles | `docs/model-profiles.md` | List profiles, set `NIM_MODEL_PROFILE` | +| Service API keys | `docs/api-key.md` | Set per-service `*_APIKEY` vars | +| Collection schema | `docs/milvus-schema.md` | Required fields: pk, vector, text, source, content_metadata | + +## Agent-Specific Notes + +- Nemotron-3-Nano naming: `nvidia/nemotron-3-nano-30b-a3b` (NVIDIA-hosted) vs `nvidia/nemotron-3-nano` (self-hosted NIM) — same model, different names +- Helm model changes go in `values.yaml` under `nimOperator` and `envVars` sections +- Custom VDB operator requires implementing `VDBRag` base class — see `docs/change-vectordb.md` "Custom Vector Database Operator" section +- VDB auth tokens can be passed per-request via `Authorization: Bearer ` header +- Milvus password persists in etcd volume — to change after deployment, must delete volumes (destroys data) + +## Notebooks +- `notebooks/building_rag_vdb_operator.ipynb` — Custom VDB operator implementation (OpenSearch example) + +## Source Documentation +- `docs/change-model.md` — Model changes (LLM, embedding, ranking, NIM images) +- `docs/change-vectordb.md` — Vector DB switching, Elasticsearch setup, custom VDB operator +- `docs/milvus-configuration.md` — Milvus indexing, GPU config, auth, tuning +- `docs/milvus-schema.md` — Collection schema fields and requirements +- `docs/model-profiles.md` — NIM profile definitions and selection +- `docs/api-key.md` — NGC API key setup, per-service keys, fallback order +- `docs/service-port-gpu-reference.md` — Port mappings and GPU assignments for all services diff --git a/optional-skills/mlops/nvidia/rag-blueprint/references/configure/multimodal-query.md b/optional-skills/mlops/nvidia/rag-blueprint/references/configure/multimodal-query.md new file mode 100644 index 0000000000000..783b6c209f0d1 --- /dev/null +++ b/optional-skills/mlops/nvidia/rag-blueprint/references/configure/multimodal-query.md @@ -0,0 +1,35 @@ +# Multimodal Query (Image + Text) + +## When to Use +- User wants to query knowledge base with images and text together +- User asks about VLM (Vision Language Model) deployment for RAG +- User wants image-based document understanding or visual Q&A + +## Restrictions +- Not available with Elasticsearch — Milvus only +- Reranker must be disabled (`ENABLE_RERANKER=false`) +- Summarization not supported (VLM replaces LLM) +- On-prem: requires NVIDIA H100 or A100 SXM 80GB GPU +- Single-page retrieval only — image queries return content from one page per document + +## Process +1. Detect the deployment mode (Docker / Helm / Library). Docker: edit the active env file. Helm: edit `values.yaml`. Library: edit `notebooks/config.yaml` +2. Read `docs/multimodal-query.md` for full env var configuration and commands +3. Choose variant: self-hosted (Docker), NVIDIA-hosted (cloud), or Helm +4. Deploy VLM + VLM Embedding NIMs per source doc instructions +5. Set VLM env vars in the active config and switch embedding model to VLM embedding +6. Restart ingestor + RAG server (Docker: add `--build` flag) and verify + +## Agent-Specific Notes +- Must select a collection before querying — queries without collection return no results +- First VLM deployment: model downloads take 10–20 min (~10GB+) +- `VLM_MS_GPU_ID` — read `docs/service-port-gpu-reference.md` for the default GPU assignment and override if needed +- Cloud rate limits apply for ingestion of >10 files +- For Helm with MIG: ensure dedicated MIG slice is assigned to VLM +- Image extraction must be enabled: `APP_NVINGEST_EXTRACTIMAGES=True`, `APP_NVINGEST_IMAGE_ELEMENTS_MODALITY=image` + +## Notebooks +- `notebooks/image_input.ipynb` — end-to-end multimodal query examples, image upload, VLM querying + +## Source Documentation +- `docs/multimodal-query.md` — full Docker/cloud/Helm configuration, env vars, API usage, limitations diff --git a/optional-skills/mlops/nvidia/rag-blueprint/references/configure/notebooks.md b/optional-skills/mlops/nvidia/rag-blueprint/references/configure/notebooks.md new file mode 100644 index 0000000000000..544de03bb9317 --- /dev/null +++ b/optional-skills/mlops/nvidia/rag-blueprint/references/configure/notebooks.md @@ -0,0 +1,50 @@ +# Notebooks + +## When to Use +- Hands-on examples of NVIDIA RAG Blueprint features are needed +- There are questions about Jupyter notebooks, tutorials, or code samples + +## Process +1. Read `docs/notebooks.md` for full notebook descriptions and prerequisites. +2. Set up the environment: virtualenv, `jupyterlab`, and `git lfs pull` for test data. +3. Open JupyterLab at `http://:8889`. + +## Agent-Specific Notes +- Git LFS is required because several notebooks rely on large data files (`git lfs install && git lfs pull`). +- In Docker mode, deploy NVIDIA RAG Blueprint first, then run notebooks against the running services. +- In library mode, use `rag_library_usage.ipynb` (full) or `rag_library_lite_usage.ipynb` (containerless). +- The custom VDB operator notebook requires Docker for OpenSearch services. + +## Notebook Catalog + +### Beginner +| Notebook | Topic | +|-----------------------------|-------------------------------------| +| `ingestion_api_usage.ipynb` | Document ingestion through the API | +| `retriever_api_usage.ipynb` | Search and retrieval API | +| `image_input.ipynb` | Image upload and multimodal queries | + +### Intermediate +| Notebook | Topic | +|--------------------------------|----------------------------------------| +| `summarization.ipynb` | Document summarization strategies | +| `evaluation_01_ragas.ipynb` | RAGAS accuracy, relevancy, groundedness| +| `evaluation_02_recall.ipynb` | Recall at top-k cutoffs | +| `nb_metadata.ipynb` | Custom metadata and filtered retrieval | +| `rag_library_usage.ipynb` | Full library mode end-to-end | +| `rag_library_lite_usage.ipynb` | Lite, containerless library mode | + +### Advanced +| Notebook | Topic | +|-----------------------------------|-------------------------------------| +| `building_rag_vdb_operator.ipynb` | Custom OpenSearch VDB operator | +| `mcp_server_usage.ipynb` | MCP server with transport modes | +| `nat_mcp_integration.ipynb` | NeMo Agent Toolkit plus MCP | + +### Deployment +| Notebook | Topic | +|--------------------|-----------------------| +| `launchable.ipynb` | Brev cloud deployment | + +## Source Documentation +- `docs/notebooks.md` — full notebook descriptions, setup, and prerequisites. diff --git a/optional-skills/mlops/nvidia/rag-blueprint/references/configure/observability.md b/optional-skills/mlops/nvidia/rag-blueprint/references/configure/observability.md new file mode 100644 index 0000000000000..5b291d3394374 --- /dev/null +++ b/optional-skills/mlops/nvidia/rag-blueprint/references/configure/observability.md @@ -0,0 +1,29 @@ +# Observability + +## When to Use +- User wants tracing, metrics, or monitoring for the RAG pipeline +- User asks about latency debugging, Zipkin, Grafana, or Prometheus + +## Process +1. Detect the deployment mode. Docker: edit the active env file. Helm: edit `values.yaml`. Library: edit `notebooks/config.yaml` +2. Read `docs/observability.md` for full setup (Docker and Helm) +3. Set `OPENTELEMETRY_CONFIG_FILE` and `APP_TRACING_ENABLED=True` in the active config +4. Start observability stack and restart RAG server +5. Import Grafana dashboard from `deploy/config/rag-metrics-dashboard.json` + +## Agent-Specific Notes +- Library mode: set `OPENTELEMETRY_CONFIG_FILE` in the environment for tracing; the Docker-based Prometheus/Grafana stack is independent +- Helm: Prometheus Operator CRDs must be installed before deploying with observability enabled +- Default Grafana credentials: `admin` / `admin` +- Zipkin spans cover: `query-rewriter`, `retriever`, `context-reranker`, `llm-stream` +- Span I/O visible via `traceloop.entity.input` / `traceloop.entity.output` fields + +### Quick Latency Triage +| Symptom | Check | +|---------|-------| +| Slow first token | `rag_ttft_ms` — compare retriever and reranker spans | +| Slow full response | `llm_generation_time_ms` / `llm-stream` span | +| Retrieval heavy | Compare `retrieval_time_ms` vs `context_reranker_time_ms` | + +## Source Documentation +- `docs/observability.md` -- full Docker/Helm setup, env vars, metrics reference, and dashboard import diff --git a/optional-skills/mlops/nvidia/rag-blueprint/references/configure/query-and-conversation.md b/optional-skills/mlops/nvidia/rag-blueprint/references/configure/query-and-conversation.md new file mode 100644 index 0000000000000..2f092cd970882 --- /dev/null +++ b/optional-skills/mlops/nvidia/rag-blueprint/references/configure/query-and-conversation.md @@ -0,0 +1,82 @@ +```markdown +# Query Rewriting, Query Decomposition, and Multi-Turn + +Use these features when you want the system to understand follow-up questions, rewrite queries for better retrieval, or break complex questions into smaller parts. + +## When to use + +Use these settings when: + +- You want to enable multi-turn conversations or support follow-up questions. +- You want query rewriting to improve retrieval accuracy. +- You need complex multi-hop query decomposition. +- You are configuring or debugging conversation history behavior.[file:1] + +## Restrictions + +- Query rewriting and multi-turn both require `CONVERSATION_HISTORY > 0`. If it is set to 0, query rewriting has no effect.[file:1] +- Query decomposition works only when `use_knowledge_base=true` and with a single collection.[file:1] +- On Helm, query rewriting is supported only with an on-prem LLM, not with cloud-hosted models.[file:1] + +## Dependencies + +`CONVERSATION_HISTORY` is shared by query rewriting and multi-turn, so changing it affects both behaviors. + +| Setting | Depends on | Side effect when changed | +|-------------------------|----------------------------|-----------------------------------------------------------| +| `ENABLE_QUERYREWRITER` | `CONVERSATION_HISTORY > 0` | Enabling requires conversation history; disabling has no side effects | +| `CONVERSATION_HISTORY` | — | Setting to `0` also effectively disables query rewriting |[file:1] + +## Process + +First detect the deployment mode. +- Docker: edit the active environment file. +- Helm: edit `values.yaml`. +- Library: edit `notebooks/config.yaml`.[file:1] + +### Query rewriting + +1. Review `docs/multiturn.md` for full configuration details.[file:1] +2. To enable, set `ENABLE_QUERYREWRITER=True`. If `CONVERSATION_HISTORY` is `0`, set it to `5` or another positive value.[file:1] +3. To disable, unset or comment out `ENABLE_QUERYREWRITER`.[file:1] +4. Restart the RAG server.[file:1] + +### Multi-turn + +1. Review `docs/multiturn.md` for configuration, retrieval strategies, and API usage.[file:1] +2. To enable, set `CONVERSATION_HISTORY > 0` and choose the retrieval strategy you want to use.[file:1] +3. To disable, set `CONVERSATION_HISTORY=0`.[file:1] +4. Restart the RAG server.[file:1] + +### Query decomposition + +1. Review `docs/query_decomposition.md` for the decomposition algorithm, limitations, and examples.[file:1] +2. Set `ENABLE_QUERY_DECOMPOSITION=true` and `MAX_RECURSION_DEPTH=3` (or a different depth that fits your use case).[file:1] +3. Restart the RAG server.[file:1] + +## Decision table + +| Goal | Source doc | Key settings | +|-------------------------------|----------------------------|-----------------------------------------------------------| +| Multi-turn with best accuracy | `docs/multiturn.md` | `CONVERSATION_HISTORY=5`, `ENABLE_QUERYREWRITER=True` | +| Multi-turn with low latency | `docs/multiturn.md` | `CONVERSATION_HISTORY=5`, `MULTITURN_RETRIEVER_SIMPLE=True` | +| Complex multi-hop queries | `docs/query_decomposition.md` | `ENABLE_QUERY_DECOMPOSITION=true`, `MAX_RECURSION_DEPTH=3` | +| Disable multi-turn (default) | — | `CONVERSATION_HISTORY=0` |[file:1] + +## Agent-specific notes + +- `MULTITURN_RETRIEVER_SIMPLE` only applies when query rewriting is disabled. If both are configured, query rewriting takes precedence.[file:1] +- You can toggle query rewriting per request by setting `enable_query_rewriting: true` in `POST /generate`, but `CONVERSATION_HISTORY` must still be greater than 0.[file:1] +- By default, multi-turn is disabled with `CONVERSATION_HISTORY=0`.[file:1] +- Query decomposition adds latency and is most useful for multi-hop queries that involve multiple entities or steps.[file:1] +- In library mode, configure these settings in `notebooks/config.yaml` instead of using environment variables.[file:1] + +## Notebooks + +- `notebooks/retriever_api_usage.ipynb`: RAG retriever API usage with search and end-to-end query examples.[file:1] + +## Source documentation + +- `docs/query_decomposition.md`: Decomposition algorithm details, when to use it, and recursion depth guidance.[file:1] +- `docs/multiturn.md`: Conversation history behavior, retrieval strategies, API usage, and Helm configuration.[file:1] +``` diff --git a/optional-skills/mlops/nvidia/rag-blueprint/references/configure/reasoning-and-generation.md b/optional-skills/mlops/nvidia/rag-blueprint/references/configure/reasoning-and-generation.md new file mode 100644 index 0000000000000..d5bb241146e44 --- /dev/null +++ b/optional-skills/mlops/nvidia/rag-blueprint/references/configure/reasoning-and-generation.md @@ -0,0 +1,57 @@ +# Reasoning, Self-Reflection & Prompt Customization + +## When to Use +User wants to enable reasoning/thinking mode, configure self-reflection, customize prompts, adjust generation parameters (max tokens, temperature, citations), or understand thinking budget options. + +## Process +1. Detect the deployment mode (Docker / Helm / Library). Docker: edit the active env file. Helm: edit `values.yaml`. Library: edit `notebooks/config.yaml` +2. Read the relevant source doc for the specific feature +3. Apply env vars to the active config or edit prompt files, restart RAG server +4. Prompt changes require `--build` flag (Docker); env var changes only need restart +5. Verify: test with a query and check for reasoning output or changed behavior + +## Decision Table + +| Goal | Source Doc | Key Action | +|------|-----------|------------| +| Enable reasoning (Nemotron 1.5) | `docs/enable-nemotron-thinking.md` | Edit `prompt.yaml`: `/no_think` → `/think`, set temperature | +| Enable reasoning (Nano 30B) | `docs/enable-nemotron-thinking.md` | `ENABLE_NEMOTRON_3_NANO_THINKING=true` | +| Self-reflection | `docs/self-reflection.md` | `ENABLE_REFLECTION=true`, set thresholds | +| Prompt customization | `docs/prompt-customization.md` | `PROMPT_CONFIG_FILE=/path/to/custom.yaml` or edit prompt.yaml | +| Generation parameters | `docs/llm-params.md` | `LLM_MAX_TOKENS`, `LLM_TEMPERATURE`, `ENABLE_CITATIONS` | +| Per-request overrides | `docs/llm-params.md` | `temperature`, `top_p`, `max_tokens`, `stop` in API payload | + +## Agent-Specific Notes + +- Prompt changes need `--build` flag on restart; env var changes do not +- Self-reflection: streaming not supported during groundedness checks +- Self-reflection uses same LLM by default; override with `REFLECTION_LLM`, `REFLECTION_LLM_SERVERURL`, `REFLECTION_LLM_APIKEY` +- Helm: only on-premises reflection is supported +- GPU requirements for reflection: see `docs/self-reflection.md` for optimal GPU configurations +- Debug reflection: set `LOGLEVEL=INFO` to observe iteration counts +- `FILTER_THINK_TOKENS=false` to see full reasoning output (filtered by default) +- 18 prompt templates available in `prompt.yaml` — custom file only overrides specified keys + +### Reasoning Model Comparison + +| Model | Control | Thinking Budget | Output Format | +|-------|---------|-----------------|---------------| +| Nemotron 1.5 | System prompt (`/think`) | None | `` tags (filtered by default) | +| Nemotron-3-Nano 9B | System prompt (`/think`) | `min_thinking_tokens` + `max_thinking_tokens` | `reasoning_content` field | +| Nemotron-3-Nano 30B | `ENABLE_NEMOTRON_3_NANO_THINKING` env var | `max_thinking_tokens` only | `reasoning_content` field | + +### Thinking Budget Recommendations + +| Range | Use Case | +|-------|----------| +| 1024–4096 | Faster responses for simpler questions | +| 8192–16384 | More thorough reasoning for complex queries | + +## Notebooks +- `notebooks/retriever_api_usage.ipynb` — end-to-end query examples showing generation behavior + +## Source Documentation +- `docs/enable-nemotron-thinking.md` — Reasoning mode for all Nemotron models +- `docs/self-reflection.md` — Self-reflection configuration and thresholds +- `docs/prompt-customization.md` — Prompt template catalog and customization +- `docs/llm-params.md` — Generation parameters (temperature, max tokens, etc.) diff --git a/optional-skills/mlops/nvidia/rag-blueprint/references/configure/search-and-retrieval.md b/optional-skills/mlops/nvidia/rag-blueprint/references/configure/search-and-retrieval.md new file mode 100644 index 0000000000000..b311c958da3c6 --- /dev/null +++ b/optional-skills/mlops/nvidia/rag-blueprint/references/configure/search-and-retrieval.md @@ -0,0 +1,67 @@ +# Search & Retrieval: Hybrid Search, Multi-Collection, Metadata & Profiles + +## When to Use +User wants to enable hybrid search, query multiple collections, add custom metadata/filters, tune retrieval performance, configure reranker, enable natural language filter generation, or switch accuracy/performance profiles. + +## Process + +1. Detect the deployment mode (Docker / Helm / Library). Docker: edit the active env file. Helm: edit `values.yaml`. Library: edit `notebooks/config.yaml` +2. Read the relevant source doc for detailed configuration +3. Apply the required env vars to the active config and restart affected services +4. Verify via search/generate API call + +## Decision Table + +| Goal | Source Doc | Key Env Vars | +|------|-----------|-------------| +| Hybrid search | `docs/hybrid_search.md` | `APP_VECTORSTORE_SEARCHTYPE=hybrid` | +| Multi-collection | `docs/multi-collection-retrieval.md` | `enable_reranker: True` in API payload | +| Custom metadata | `docs/custom-metadata.md` | Metadata in upload payload, `vdb_filter_expression` in query | +| Accuracy profile | `docs/accuracy_perf.md` | Copy values from `deploy/compose/accuracy_profile.env` into the active env file | +| Performance profile | `docs/accuracy_perf.md` | Copy values from `deploy/compose/perf_profile.env` into the active env file | +| Filter generation | `docs/custom-metadata.md` | `ENABLE_FILTER_GENERATOR=True` | + +## Agent-Specific Notes + +- Hybrid search requires re-ingesting — existing collections created with `dense` must be re-created +- Multi-collection: limited to 5 collections per query; reranker is mandatory +- Multi-collection not supported when `ENABLE_QUERY_DECOMPOSITION=true` +- Elasticsearch RRF not supported in open-source version — must use `weighted` ranker +- Ingestor must be restarted alongside RAG server when enabling hybrid search +- `RERANKER_CONFIDENCE_THRESHOLD` is a legacy alias for `RERANKER_SCORE_THRESHOLD` +- Recommended `RERANKER_SCORE_THRESHOLD` range: 0.3–0.5 (too high filters out too many chunks) + +### Advanced Tuning (not fully documented elsewhere) + +| Variable | Default | Description | +|----------|---------|-------------| +| `APP_VECTORSTORE_INDEXTYPE` | `GPU_CAGRA` | Vector index type | +| `APP_VECTORSTORE_EF` | `100` | Search accuracy/speed trade-off (must be >= `VECTOR_DB_TOPK`) | +| `VECTOR_DB_TOPK` | `100` | Candidates from vector DB (input to reranker) | +| `APP_RETRIEVER_TOPK` | `10` | Chunks sent to LLM prompt (after reranking) | +| `ENABLE_RERANKER` | `True` | Toggle reranking model | +| `RERANKER_SCORE_THRESHOLD` | `0.0` | Minimum reranker score (0.0–1.0) | +| `COLLECTION_NAME` | `multimodal_data` | Default collection name | + +### Partial Filtering +- Strict (default): fails if any collection doesn't support the filter +- Flexible (`allow_partial_filtering: true` in config.yaml): succeeds if at least one collection supports it + +### VDB Filter Support + +| Feature | Milvus | Elasticsearch | +|---------|--------|---------------| +| NL filter generation | LLM-powered | Not supported (manual DSL) | +| Filter syntax | String expressions | List of dicts (ES Query DSL) | +| UI support | Full filtering interface | API only | + +## Notebooks +- `notebooks/retriever_api_usage.ipynb` — RAG retriever API: search and end-to-end queries +- `notebooks/nb_metadata.ipynb` — Metadata ingestion, filtering, and extraction from queries + +## Source Documentation +- `docs/hybrid_search.md` — Hybrid dense + sparse search configuration +- `docs/multi-collection-retrieval.md` — Multi-collection querying +- `docs/custom-metadata.md` — Custom metadata schema, filtering expressions, filter generation +- `docs/accuracy_perf.md` — Best practices for tuning ingestion/retrieval/generation settings +- `docs/python-client.md` — Python library API for search and filtering diff --git a/optional-skills/mlops/nvidia/rag-blueprint/references/configure/summarization.md b/optional-skills/mlops/nvidia/rag-blueprint/references/configure/summarization.md new file mode 100644 index 0000000000000..299c41e89b441 --- /dev/null +++ b/optional-skills/mlops/nvidia/rag-blueprint/references/configure/summarization.md @@ -0,0 +1,40 @@ +# Document Summarization + +## When to Use +- User wants to generate summaries during document ingestion +- User asks about summarization strategies or options +- User wants to check summary status or progress + +## Restrictions +- Not supported in lite mode (containerless/library-only deployment) +- Requires Redis for status tracking and rate limiting +- Collection must exist before uploading with `generate_summary: true` + +## Process +1. Detect the deployment mode. Docker: edit the active env file. Helm: configure under `ingestor-server.envVars` in `values.yaml`. Library: use the upload API parameters directly (no env vars needed) +2. Read `docs/summarization.md` for full configuration, env vars, and prompt customization +3. Set `generate_summary: true` in the upload payload (per-request, no global toggle) +4. Optionally configure `summary_options`: strategy, shallow mode, page filter +5. Retrieve summary via `GET /v1/summary?collection_name=...&file_name=...` + +## Decision Table + +| Goal | Strategy | Notes | +|------|----------|-------| +| Fastest overview | `"single"` + `shallow_summary=true` + `page_filter` | Quick text-only extraction | +| Best quality | `null` (iterative, default) + `shallow_summary=false` | Sequential refinement | +| Balanced | `"hierarchical"` + `shallow_summary=true` | Parallel tree-based | + +## Agent-Specific Notes +- `CONVERSATION_HISTORY` prerequisite does not apply — that's for query rewriting only +- `SUMMARY_LLM_SERVERURL=""` (empty) routes to NVIDIA cloud; `"nim-llm:8000"` for self-hosted +- `SUMMARY_LLM_MAX_CHUNK_LENGTH` should be below the model's context window to leave room for prompt + output +- Redis semaphore auto-resets on ingestor startup (prevents stale values from crashes) +- If Redis is unavailable, summaries still generate but no real-time status tracking +- Status entries have 24-hour TTL in Redis + +## Notebooks +- `notebooks/summarization.ipynb` — complete examples for all strategies, status polling, library mode usage + +## Source Documentation +- `docs/summarization.md` — env var reference, prompt customization, rate limiting, chunking details diff --git a/optional-skills/mlops/nvidia/rag-blueprint/references/configure/user-interface.md b/optional-skills/mlops/nvidia/rag-blueprint/references/configure/user-interface.md new file mode 100644 index 0000000000000..7fbad8165b294 --- /dev/null +++ b/optional-skills/mlops/nvidia/rag-blueprint/references/configure/user-interface.md @@ -0,0 +1,27 @@ +# User Interface + +## When to Use +- User asks about the RAG UI, uploading documents, settings, or metadata filtering +- User wants to configure features via the web interface + +## Restrictions +- Sample/experimentation UI — not intended for production +- 100-file limit per upload batch; use multiple batches or API for bulk uploads +- 10 MB max per image attachment + +## Process +1. Read `docs/user-interface.md` for full UI documentation +2. Access at `http://localhost:8090` (or `http://:8090` for remote) +3. Configure RAG settings and feature toggles via Settings panel +4. Use Filter Bar above chat input for metadata-filtered queries + +## Agent-Specific Notes +- VLM Inference must be enabled in Settings > Feature Toggles before image attachments work +- ECONNRESET errors on multi-file uploads — recommend API for bulk operations +- Document summaries generate asynchronously; UI shows "Generating summary..." until complete +- Document count in UI may lag slightly after ingestion +- Metadata filtering supports AND/OR logic between filters (toggle via logic button) +- Custom metadata schema is set during collection creation via the Metadata Schema Editor + +## Source Documentation +- `docs/user-interface.md` -- full UI documentation including settings, file types, metadata, and health monitoring diff --git a/optional-skills/mlops/nvidia/rag-blueprint/references/configure/vlm.md b/optional-skills/mlops/nvidia/rag-blueprint/references/configure/vlm.md new file mode 100644 index 0000000000000..d573cd0c2a8ca --- /dev/null +++ b/optional-skills/mlops/nvidia/rag-blueprint/references/configure/vlm.md @@ -0,0 +1,56 @@ +# VLM, VLM Embeddings & Image Captioning + +## When to Use +User wants image understanding, visual content analysis, VLM inference, multimodal embeddings, or image captioning during ingestion. + +## Restrictions +- Not available on B200 GPUs — use H100, A100 SXM 80GB, or RTX PRO 6000 +- Requires extra GPU (GPU 1+ for 2-GPU systems, GPU 2+ for 3+ GPUs with fallback) +- VLM embeddings: experimental, PDF-only, no summarization, no citations with page-as-image +- Image captioning on Helm: on-prem only (modify `values.yaml` to enable) + +## Process +1. Detect the deployment mode (Docker / Helm / Library). Docker: edit the active env file. Helm: edit `values.yaml`. Library: edit `notebooks/config.yaml` +2. Read the relevant source doc for detailed steps: + - VLM generation: `docs/vlm.md` + - VLM embeddings: `docs/vlm-embed.md` + - Image captioning: `docs/image_captioning.md` +3. Start VLM NIM (self-hosted) or configure cloud endpoint (NVIDIA-hosted) +4. Set the required variables in the active config: + - Enabling: `ENABLE_VLM_INFERENCE=true` and `APP_NVINGEST_EXTRACTIMAGES=True` + - Disabling: re-comment those variables in the env file +5. Restart affected services and verify with a health check + image-containing document query + +## Decision Table + +| Goal | Source Doc | Docker Profile | Notes | +|------|-----------|---------------|-------| +| VLM replaces LLM | `docs/vlm.md` | `--profile vlm-generation` | LLM not started; set `VLM_TO_LLM_FALLBACK=false` | +| VLM + LLM fallback | `docs/vlm.md` | `--profile vlm-only` | Needs 3+ GPUs; both VLM and LLM running | +| VLM embeddings | `docs/vlm-embed.md` | `--profile vlm-embed` | Experimental; requires re-ingestion | +| Image captioning | `docs/image_captioning.md` | `--profile vlm-only` | Requires VLM NIM; Helm: on-prem only | +| Multimodal query | `docs/multimodal-query.md` | (depends on VLM mode) | Image + text querying | + +## Agent-Specific Notes + +- `--profile vlm-generation` skips the LLM entirely — use `--profile vlm-only` for fallback mode +- `VLM_TO_LLM_FALLBACK` defaults to `true`, but `vlm-generation` profile does not start LLM +- Helm VLM: disable `nim-llm` and enable `nim-vlm` (VLM uses LLM's GPU allocation) +- Helm fallback: keep both `nim-vlm` and `nim-llm` enabled, set `VLM_TO_LLM_FALLBACK: "true"` +- VLM context window is limited — keep queries self-contained +- Image captioning known issue: files without graphs/charts/tables/plots fail to ingest when captioning is enabled + +### Key Env Vars (always needed) +- `ENABLE_VLM_INFERENCE=true` — master toggle +- `APP_NVINGEST_EXTRACTIMAGES=True` — extract images during ingestion +- `VLM_MS_GPU_ID=` — self-hosted GPU assignment + +## Notebooks +- `notebooks/image_input.ipynb` — Multimodal queries with VLM (text + image) + +## Source Documentation +- `docs/vlm.md` — VLM generation (self-hosted, NVIDIA-hosted, Helm, Library) +- `docs/vlm-embed.md` — VLM embeddings (experimental) +- `docs/image_captioning.md` — Image captioning during ingestion +- `docs/multimodal-query.md` — Image + text querying +- `docs/service-port-gpu-reference.md` — default GPU assignments for VLM and other NIMs diff --git a/optional-skills/mlops/nvidia/rag-blueprint/references/deploy.md b/optional-skills/mlops/nvidia/rag-blueprint/references/deploy.md new file mode 100644 index 0000000000000..96d712892de4c --- /dev/null +++ b/optional-skills/mlops/nvidia/rag-blueprint/references/deploy.md @@ -0,0 +1,119 @@ +# RAG Blueprint Deployment + +## Phase 1: Environment Analysis + +Run this single command to collect all environment information at once: + +```bash +echo "=== GPU ===" && nvidia-smi --query-gpu=index,name,memory.total --format=csv,noheader 2>/dev/null || echo "NO_GPU"; echo "=== VRAM ===" && nvidia-smi --query-gpu=memory.total --format=csv,noheader,nounits 2>/dev/null | awk '{s+=$1} END {print s "MB total"}' || echo "0MB total"; echo "=== DRIVER ===" && cat /proc/driver/nvidia/version 2>/dev/null | head -1 || echo "NO_DRIVER"; echo "=== CUDA ===" && nvcc --version 2>/dev/null | grep "release" || echo "NO_CUDA_TOOLKIT"; echo "=== DOCKER ===" && docker --version 2>/dev/null || echo "NO_DOCKER"; echo "=== COMPOSE ===" && docker compose version 2>/dev/null || echo "NO_COMPOSE"; echo "=== NVIDIA_TOOLKIT ===" && docker info 2>/dev/null | grep -i "runtimes.*nvidia" || echo "NO_NVIDIA_TOOLKIT"; echo "=== PYTHON ===" && python3 --version 2>/dev/null || echo "NO_PYTHON"; echo "=== DISK ===" && df -h --output=avail / | tail -1; echo "=== OS ===" && cat /etc/os-release 2>/dev/null | grep -E "^(NAME|VERSION)="; echo "=== NGC_KEY ===" && if [ -n "$NGC_API_KEY" ]; then echo "NGC_KEY_SET"; elif [ -n "$NVIDIA_API_KEY" ]; then echo "NVIDIA_KEY_SET"; elif grep -qr "NGC_API_KEY=" deploy/compose/.env deploy/compose/nvdev.env 2>/dev/null | grep -qv "nvapi-your-key"; then echo "DOTENV_SET"; else echo "NOT_SET"; fi; echo "=== RUNNING ===" && docker ps --format "{{.Names}}" 2>/dev/null | grep -E "(rag-server|ingestor-server|nim-llm|milvus)" | head -10 || echo "NO_RUNNING_SERVICES"; echo "=== PORTS ===" && (ss -tlnp 2>/dev/null || netstat -tlnp 2>/dev/null) | grep -E ":(8081|8082|8090|19530) " || echo "PORTS_FREE"; echo "=== REPO ===" && git rev-parse --show-toplevel 2>/dev/null && git describe --tags 2>/dev/null || echo "NO_GIT_REPO"; echo "=== CACHE ===" && du -sh ~/.cache/model-cache/ 2>/dev/null || echo "NO_CACHE" +``` + +Present a summary table: + +| Check | Result | +|-------|--------| +| GPU(s) | (list with VRAM, or NO_GPU) | +| Total VRAM | (sum in MB/GB) | +| NVIDIA Driver | (version or NO_DRIVER) | +| CUDA Toolkit | (version or NO_CUDA_TOOLKIT) | +| Docker | (version or NO_DOCKER) | +| Docker Compose | (version or NO_COMPOSE) | +| NVIDIA Container Toolkit | (detected or NO_NVIDIA_TOOLKIT) | +| Python | (version or NO_PYTHON) | +| Free disk | (value) | +| OS | (name + version) | +| NGC_API_KEY | ENV_SET / DOTENV_SET / NOT_SET | +| Existing services | (list or none) | +| Port availability | (free or list conflicts) | +| Repo | (tag/branch or NO_GIT_REPO) | +| Model cache | (size or empty) | + +### Existing Services Warning + +If RAG services are already running, tell the user briefly: "Existing RAG services detected (list). Proceeding will restart them." Continue unless the user objects. + +If the user wants to **switch deployment modes** (e.g., NVIDIA-hosted → self-hosted, or Docker → library), shut down the existing deployment first via `references/shutdown.md`, then proceed with the new mode. + +If ports are occupied by non-RAG processes, tell the user which ports conflict and suggest stopping the conflicting process. This is a blocker. + +## Phase 2: NGC_API_KEY Handling + +Check in this order: + +1. If `NGC_API_KEY` is set in the shell environment → proceed. +2. If `NVIDIA_API_KEY` is set (common in library mode) → proceed silently. +3. If `NGC_API_KEY` is in `deploy/compose/.env` or `deploy/compose/nvdev.env` (and not the placeholder `nvapi-your-key`) → load it and proceed. +4. If none found → tell the user: "NGC_API_KEY is required. Get one from https://org.ngc.nvidia.com/setup/api-keys and run: `export NGC_API_KEY=\"nvapi-...\"` — then tell me when done." +5. After user confirms → re-check silently. If still not set, write placeholder to `.env` and tell the user to edit it. + +## Phase 3: Blocker Checks + +Automatically check and report all blockers at once (don't stop at the first one): + +Read `docs/support-matrix.md` for current minimum versions and disk requirements, then check: + +- **Docker Compose below minimum**: "Upgrade Docker Compose. See https://docs.docker.com/compose/install/linux/" +- **NVIDIA Driver below minimum** (if self-hosted): "Upgrade NVIDIA driver. See `docs/support-matrix.md` for required version." +- **NVIDIA Container Toolkit missing** (and self-hosted needed): "Install NVIDIA Container Toolkit. See https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html" +- **Insufficient disk**: "Check `docs/support-matrix.md` for disk requirements per deployment mode." +- **No Docker and no Python 3.11+**: "Install Docker or Python 3.11+ to proceed." + +List all blockers together so the user can fix them in one pass — don't make them fix one, re-run, fix another. + +## Phase 4: Route to Deployment Mode + +### User explicitly requests a mode +- "library mode" / "lite mode" / "no docker" / "python mode" → read and follow `deploy/library.md` +- "docker" / "self-hosted" / "local" → read and follow `deploy/docker.md` with mode **self-hosted** +- "cloud" / "nvidia-hosted" / "hosted" → read and follow `deploy/docker.md` with mode **nvidia-hosted** +- "retrieval only" / "search only" / "no LLM" → read and follow `deploy/docker.md` with mode **retrieval-only** +- "kubernetes" / "k8s" / "helm" → read and follow `deploy/helm.md` +- "workbench" / "ai workbench" → tell user to follow `deploy/workbench/README.md` (AI Workbench uses its own UI-driven workflow) + +### Docker is available (Docker + Compose detected) + +**Self-hosted eligible** — read `docs/support-matrix.md` ("Hardware Requirements (Docker)" section) for current GPU requirements. All of the following must also be true: +- GPU count and type matches the Docker self-hosted requirements from the support matrix +- ≥200 GB free disk (per `docs/support-matrix.md` "Disk Space Requirements") +- NVIDIA Container Toolkit detected +- NVIDIA driver meets minimum version from `docs/support-matrix.md` ("Driver Versions") + +If self-hosted eligible → read and follow `deploy/docker.md` with mode **self-hosted** + +**Otherwise with Docker** → read and follow `deploy/docker.md` with mode **nvidia-hosted** + +Tell the user WHY if they have some GPU but not enough: +- "You have [X GPU] with [Y GB] VRAM. Self-hosted requires [requirements from docs/support-matrix.md]. Deploying with NVIDIA-hosted cloud NIMs instead — faster startup, no model download." + +### Docker is available but Compose is not + +Tell the user: "Docker is installed but Docker Compose is below the minimum version (see `docs/support-matrix.md`). Install it: https://docs.docker.com/compose/install/linux/ — or use library mode instead." + +If user chooses library mode → read and follow `deploy/library.md` + +### Docker is not available + +- Python 3.11+ available → read and follow `deploy/library.md` with mode **lite** +- No Python → tell user to install Python 3.11+ or Docker + +## After Deployment + +Once deployment completes, verify health: + +```bash +echo "=== RAG Server ===" && curl -s http://localhost:8081/v1/health?check_dependencies=true 2>/dev/null || echo "RAG_SERVER_NOT_READY"; echo "=== Ingestor ===" && curl -s http://localhost:8082/v1/health?check_dependencies=true 2>/dev/null || echo "INGESTOR_NOT_READY" +``` + +If healthy, tell the user: +- "RAG Blueprint is running and healthy." +- "Ask me to configure features like VLM, query rewriting, guardrails, etc." +- "Ask me to shutdown when you're done." + +If unhealthy, read `references/troubleshoot.md` and diagnose. Match error output against known issues, fix, and retry. Escalate to the user only if the fix requires their action (API key, data deletion). + +## Notebooks +- `notebooks/launchable.ipynb` — Cloud deployment via Brev (alternative to local deployment) + +## Source Documentation +- `docs/support-matrix.md` — GPU requirements, driver versions, disk space, supported platforms +- `docs/service-port-gpu-reference.md` — port mappings and GPU assignments for all services diff --git a/optional-skills/mlops/nvidia/rag-blueprint/references/deploy/docker-nvidia-hosted.md b/optional-skills/mlops/nvidia/rag-blueprint/references/deploy/docker-nvidia-hosted.md new file mode 100644 index 0000000000000..f4c6ede077b61 --- /dev/null +++ b/optional-skills/mlops/nvidia/rag-blueprint/references/deploy/docker-nvidia-hosted.md @@ -0,0 +1,38 @@ +# Docker Deployment (NVIDIA-Hosted NIMs) + +## When to Use +- User wants fast deployment without local model downloads +- User has no GPU or limited GPU +- User asks about cloud-hosted or NVIDIA API deployment +- User wants to avoid 15–30 min NIM startup time + +## Restrictions +- Requires internet access (calls NVIDIA cloud APIs) +- NVIDIA-hosted endpoints have rate limits — large ingestions (>10 files) may hit 429 errors +- NGC_API_KEY required for cloud API access +- Docker and Compose minimum versions per `docs/support-matrix.md` + +## Process +1. Read `docs/deploy-docker-nvidia-hosted.md` for full commands and env configuration +2. Use `deploy/compose/nvdev.env` — pre-configured for cloud endpoints. Source it before compose commands: `source deploy/compose/nvdev.env` +3. Start vector DB → ingestor → RAG server + frontend (no NIM startup needed) +4. Verify: `docker ps` shows containers; UI at `http://localhost:8090` + +## Decision Table + +| Goal | Key Action | +|------|------------| +| Standard cloud deployment | Use `nvdev.env` (pre-configured for cloud) | +| Zero-GPU (no Milvus GPU) | Also switch Milvus image to CPU-only | +| Large file ingestion | Reduce batch/concurrency settings to avoid 429s | +| Maximum throughput | Use self-hosted deployment instead | + +## Agent-Specific Notes +- First run: 5–10 min (image pulls only); subsequent: 1–2 min +- No `nims.yaml` startup — all model inference is cloud-hosted +- All subsequent configure/restart operations should source the same env file used for the initial deploy (`deploy/compose/nvdev.env`) +- For zero-GPU: switch Milvus to CPU-only by changing the GPU image tag to the equivalent non-GPU tag and setting `APP_VECTORSTORE_ENABLEGPUSEARCH=False`. See `docs/deploy-docker-nvidia-hosted.md` for the current image tags +- Rate limit mitigation for large ingestions: reduce `NV_INGEST_FILES_PER_BATCH`, `NV_INGEST_CONCURRENT_BATCHES`, `MAX_INGEST_PROCESS_WORKERS`, `NV_INGEST_MAX_UTIL` to minimum values + +## Source Documentation +- `docs/deploy-docker-nvidia-hosted.md` — full step-by-step commands, env var blocks, CPU Milvus setup diff --git a/optional-skills/mlops/nvidia/rag-blueprint/references/deploy/docker-retrieval-only.md b/optional-skills/mlops/nvidia/rag-blueprint/references/deploy/docker-retrieval-only.md new file mode 100644 index 0000000000000..fb4935cf81d80 --- /dev/null +++ b/optional-skills/mlops/nvidia/rag-blueprint/references/deploy/docker-retrieval-only.md @@ -0,0 +1,37 @@ +# Retrieval-Only Deployment + +## When to Use +- User wants search/retrieval without LLM generation +- User asks to deploy only embedding + reranking services +- User wants `/search` endpoint with an external LLM +- User wants a lightweight, low-GPU deployment + +## Restrictions +- `/generate` endpoint returns an error — no LLM is deployed +- Self-hosted: 1 GPU, ~24 GB memory +- NVIDIA-hosted: 0 GPUs (cloud embedding + reranking) + +## Process +1. Read `docs/retrieval-only-deployment.md` for full commands, env vars, and API examples +2. Choose variant: self-hosted (local NIMs), NVIDIA-hosted (cloud), or Helm +3. For self-hosted: start only embedding + ranking NIMs, skip LLM +4. For NVIDIA-hosted: set embedding/ranking server URLs to empty, skip NIM startup entirely +5. For Helm: set `nimOperator.nim-llm.enabled=false` +6. Start vector DB → ingestor → RAG server +7. Verify health: `GET http://localhost:8081/v1/health?check_dependencies=true` + +## Decision Table + +| Goal | Variant | Key Difference | +|------|---------|----------------| +| Minimal GPU usage with local models | Self-hosted | 1 GPU, ~24 GB | +| Zero GPU, cloud APIs | NVIDIA-hosted | Set server URLs to empty, skip NIM startup | +| Kubernetes | Helm | Disable `nim-llm` in values.yaml | + +## Agent-Specific Notes +- Permission errors on model cache → try `USERID=0` or `chmod -R 755 ~/.cache/model-cache` +- Empty search results → verify documents ingested: `GET http://localhost:8082/v1/documents?collection_name=` +- Users can send `/search` results to their own external LLM for generation + +## Source Documentation +- `docs/retrieval-only-deployment.md` — full deployment commands, API examples, search payload options diff --git a/optional-skills/mlops/nvidia/rag-blueprint/references/deploy/docker-self-hosted.md b/optional-skills/mlops/nvidia/rag-blueprint/references/deploy/docker-self-hosted.md new file mode 100644 index 0000000000000..dc18ef64972b5 --- /dev/null +++ b/optional-skills/mlops/nvidia/rag-blueprint/references/deploy/docker-self-hosted.md @@ -0,0 +1,49 @@ +# Docker Deployment (Self-Hosted NIMs) + +## When to Use +- User wants full on-premises deployment with local NIM containers +- User has supported GPUs and wants models running locally +- User asks to deploy RAG Blueprint with Docker + +## Restrictions + +Read `docs/support-matrix.md` for current GPU requirements. Feature restrictions per GPU type: + +| GPU | Cannot Use | +|-----|------------| +| B200 | VLM, Guardrails, Nemotron Parse | +| RTX PRO 6000 | Nemotron Parse | + +- Read `docs/support-matrix.md` for current minimum NVIDIA Driver, CUDA, Docker, and Compose versions +- NVIDIA Container Toolkit required (`docker info` shows nvidia runtime) +- Disk space per `docs/support-matrix.md` ("Disk Space Requirements") +- If any prerequisite is missing, tell the user what to install before proceeding + +## Process +1. Read `docs/deploy-docker-self-hosted.md` for full commands and env configuration +2. Read `docs/support-matrix.md` for GPU compatibility and supported model combinations +3. Verify container toolkit, prepare model cache directory, source `.env` +4. Apply GPU-specific config per source docs +5. Start NIMs → wait for healthy → start remaining services +6. Verify: `docker ps` shows all containers healthy; UI at `http://localhost:8090` + +## Decision Table + +| Goal | Profile Flag | Notes | +|------|-------------|-------| +| Full deployment (default) | (none) | LLM + embedding + ranking + OCR + detection | +| Text-only RAG (lighter) | `--profile rag` | Skip OCR/detection NIMs | +| Ingestion workload only | `--profile ingest` | Embedding + OCR + detection | +| VLM replaces LLM | `--profile vlm-generation` | Not on B200 | +| Advanced PDF extraction | `--profile nemotron-parse` | Not on B200 or RTX PRO 6000 | + +## Agent-Specific Notes +- First run: 15–30 min (model downloads ~100–150 GB, no progress bar); subsequent: 2–5 min +- Monitor download progress: `du -sh ~/.cache/model-cache/` +- Permission error on model cache → try `USERID=0` instead of `USERID=$(id -u)` +- Cloud NIM section in `deploy/compose/.env` must be commented out for self-hosted +- Rebuild after code changes: add `--build` flag to compose up commands + +## Source Documentation +- `docs/deploy-docker-self-hosted.md` — full step-by-step commands, env vars, GPU assignments +- `docs/support-matrix.md` — GPU compatibility, supported models, hardware requirements diff --git a/optional-skills/mlops/nvidia/rag-blueprint/references/deploy/docker.md b/optional-skills/mlops/nvidia/rag-blueprint/references/deploy/docker.md new file mode 100644 index 0000000000000..eb31fb1a607df --- /dev/null +++ b/optional-skills/mlops/nvidia/rag-blueprint/references/deploy/docker.md @@ -0,0 +1,88 @@ +# RAG Docker Deployment + +## Determine Mode + +If routed here from the deploy workflow, the mode (self-hosted, nvidia-hosted, or retrieval-only) was already decided. Use it. + +If invoked directly without a mode, auto-detect: + +```bash +echo "=== COMPOSE ===" && docker compose version 2>/dev/null || echo "NO_COMPOSE"; echo "=== GPU ===" && nvidia-smi --query-gpu=name,memory.total --format=csv,noheader 2>/dev/null || echo "NO_GPU"; echo "=== DISK ===" && df -h --output=avail / | tail -1; echo "=== RUNNING ===" && docker ps --format "{{.Names}}" 2>/dev/null | grep -E "(rag-server|ingestor-server|nim-llm|milvus)" | head -10 || echo "NONE_RUNNING" +``` + +If NO_COMPOSE: stop and tell the user to install Docker Compose (see `docs/support-matrix.md` for minimum version). + +Read `docs/support-matrix.md` ("Hardware Requirements (Docker)" section) for current GPU requirements, then: +- GPU count/type meets self-hosted requirements from the support matrix, and 200+ GB free disk → **self-hosted** +- Any GPU or no GPU with ≥50 GB free disk → **nvidia-hosted** +- User explicitly says "retrieval only" / "no LLM" / "search only" → **retrieval-only** + +Auto-route based on hardware. Only ask if two modes are equally valid and the user's intent is ambiguous. + +## Verify NGC_API_KEY + +Auto-check all possible locations before asking: + +```bash +[ -n "$NGC_API_KEY" ] && echo "ENV_SET" || (grep -qr "NGC_API_KEY=" deploy/compose/.env deploy/compose/nvdev.env 2>/dev/null | grep -qv "nvapi-your-key" && echo "DOTENV_SET" || echo "NOT_SET") +``` + +- **ENV_SET**: proceed silently. +- **DOTENV_SET**: load the env file that contains the key and proceed. +- **NOT_SET**: ask the user to provide it. This is the only thing to ask for. + +## Docker Login + +Auto-check if already logged in: + +```bash +grep -q "nvcr.io" ~/.docker/config.json 2>/dev/null && echo "ALREADY_LOGGED_IN" || echo "NOT_LOGGED_IN" +``` + +If already logged in → proceed silently. + +If not logged in → tell the user to run this themselves (the key gets expanded in agent logs): + +> Please run in your terminal: `echo "${NGC_API_KEY}" | docker login nvcr.io -u '$oauthtoken' --password-stdin` + +Wait for confirmation only if login was needed. + +## Deploy + +Based on the mode, read and follow the appropriate reference: + +- **Self-hosted**: read and follow `docker-self-hosted.md` +- **NVIDIA-hosted**: read and follow `docker-nvidia-hosted.md` +- **Retrieval-only**: read and follow `docker-retrieval-only.md` + +## Post-Deploy Verification + +Run health checks: + +```bash +sleep 5; echo "=== RAG ===" && curl -s http://localhost:8081/v1/health?check_dependencies=true 2>/dev/null || echo "RAG_NOT_READY"; echo "=== INGESTOR ===" && curl -s http://localhost:8082/v1/health?check_dependencies=true 2>/dev/null || echo "INGESTOR_NOT_READY"; echo "=== CONTAINERS ===" && docker ps --format "table {{.Names}}\t{{.Status}}" 2>/dev/null | grep -E "(rag|milvus|nim|ingest)" | head -15 +``` + +If services are still initializing, automatically poll every 30 seconds: +- **NVIDIA-hosted**: poll until healthy or 5 minutes elapsed (no model downloads needed). +- **Self-hosted**: poll until healthy or 15 minutes elapsed (model downloads on first run). +- **Retrieval-only**: poll until healthy or 5 minutes elapsed. + +Show progress to the user during polling. + +## On Success + +Tell the user: +- "RAG Blueprint is running and healthy. Open http://localhost:8090 to use the UI." (skip for retrieval-only) +- "Ask me to configure features (VLM, query rewriting, guardrails, etc.)" +- "Ask me to shutdown when you're done." + +## On Error + +1. Read the error output from the failed command. +2. Read `references/troubleshoot.md` to match against common issues (port conflict, disk full, NGC auth, GPU OOM). +3. Apply the fix and retry. +4. If still failing, report the specific error to the user with the fix that was attempted. + +## Source Documentation +- `docs/support-matrix.md` — GPU requirements, hardware compatibility, disk space diff --git a/optional-skills/mlops/nvidia/rag-blueprint/references/deploy/helm-mig.md b/optional-skills/mlops/nvidia/rag-blueprint/references/deploy/helm-mig.md new file mode 100644 index 0000000000000..dd3dd8ce3eaf3 --- /dev/null +++ b/optional-skills/mlops/nvidia/rag-blueprint/references/deploy/helm-mig.md @@ -0,0 +1,38 @@ +# MIG GPU Deployment + +## When to Use +- User wants fine-grained GPU allocation on Kubernetes using MIG slices +- User has H100 GPUs and wants to share them across RAG services +- User asks about Multi-Instance GPU deployment + +## Restrictions +- Requires H100 80GB HBM3 GPUs (MIG-compatible) +- MIG profiles in this guide are specific to H100 80GB — other GPUs need different profiles +- Requires cloned repository (MIG config files in `deploy/helm/`) +- All standard Helm prerequisites apply (GPU Operator, NIM Operator, StorageClass) +- Ingestion profile is scaled down with MIG — large bulk ingestion jobs may fail + +## Process +1. Read `docs/mig-deployment.md` for full configuration, commands, and MIG slice definitions +2. Enable MIG with mixed strategy on ClusterPolicy +3. Apply MIG ConfigMap and label the node +4. Verify node labels show `mig.config.state: "success"` before proceeding +5. Install Helm chart with `-f mig-slicing/values-mig.yaml` + +## Decision Table + +| Goal | Source Doc | Key Action | +|------|-----------|------------| +| Standard MIG on H100 | `docs/mig-deployment.md` | Apply MIG config, label node, install chart | +| RTX PRO 6000 with MIG | `docs/mig-deployment.md` | Also uncomment model section in values.yaml | +| Custom MIG profiles | NVIDIA MIG User Guide | Modify `mig-config.yaml` for different GPU types | + +## Agent-Specific Notes +- Must wait for `mig.config.state: "success"` on the node before Helm install — if not present, wait and re-check +- Default H100 MIG layout (see `docs/mig-deployment.md` for current GPU count and slice definitions): GPU 0 → small slices, GPU 1 → mixed slices, GPU 2 → full-GPU slice +- LLM gets the largest slice (`7g.80gb`); embedding/Milvus/ingest share small slices +- RTX PRO 6000 variant: uncomment model section in values.yaml, then use both `-f values.yaml -f mig-slicing/values-mig.yaml` +- Uninstall follows standard Helm procedure (see Helm deployment docs) + +## Source Documentation +- `docs/mig-deployment.md` — full MIG config, ClusterPolicy patches, node labeling, verification, Helm install commands diff --git a/optional-skills/mlops/nvidia/rag-blueprint/references/deploy/helm-standard.md b/optional-skills/mlops/nvidia/rag-blueprint/references/deploy/helm-standard.md new file mode 100644 index 0000000000000..df2630660569a --- /dev/null +++ b/optional-skills/mlops/nvidia/rag-blueprint/references/deploy/helm-standard.md @@ -0,0 +1,51 @@ +# Helm Deployment + +## When to Use +- User wants to deploy RAG Blueprint on Kubernetes +- User asks about Helm chart installation (from NGC or local repo) +- User mentions Kubernetes, k8s, or Helm in deployment context + +## Restrictions + +Read `docs/support-matrix.md` for current Kubernetes, Helm, and OS version requirements. + +- Requires GPU Operator + NIM Operator pre-installed +- Default StorageClass must be configured for PVC provisioning +- Disk space per `docs/support-matrix.md` +- NeMo Guardrails not available in Helm deployment +- Image captioning: on-prem only (requires `values.yaml` changes; see `docs/image_captioning.md`) + +## Process + +### Option A: Deploy from NGC (Remote Chart) +1. Read `docs/deploy-helm.md` for full commands and values +2. Ensure prerequisites: GPU Operator, NIM Operator, StorageClass, NGC_API_KEY +3. Install chart, monitor pods, port-forward frontend + +### Option B: Deploy from Repository (Local Chart) +1. Read `docs/deploy-helm-from-repo.md` for full commands and repo setup +2. Add required Helm repos, run `helm dependency update`, install from local path + +### RTX PRO 6000 Variant +1. Uncomment model section under `nimOperator.nim-llm.model` in `values.yaml` +2. See source docs for engine/precision/GPU settings + +## Decision Table + +| Goal | Option | Key Action | +|------|--------|------------| +| Quick deploy from published chart | NGC (Option A) | `helm upgrade --install` with NGC URL | +| Customized chart | Local repo (Option B) | Clone, modify values, `helm dependency update` | +| RTX PRO 6000 GPUs | Either option | Uncomment model section in values.yaml | +| Retrieval-only (no LLM) | Either option | `--set nimOperator.nim-llm.enabled=false` | + +## Agent-Specific Notes +- First deployment: 60–70 min (model cache download); subsequent: 10–15 min +- Pods in `ContainerCreating`/`Init` for extended time is normal during cache download +- PVCs are not removed by `helm uninstall` — delete manually: `kubectl delete nimcache --all -n rag && kubectl delete pvc --all -n rag` +- Port-forwarding may timeout for large file ingestion — not suitable for bulk uploads +- All configurable endpoints documented in `deploy/helm/nvidia-blueprint-rag/endpoints.md` + +## Source Documentation +- `docs/deploy-helm.md` — NGC remote chart deployment, prerequisites, monitoring +- `docs/deploy-helm-from-repo.md` — local chart deployment, repo setup, dependency management diff --git a/optional-skills/mlops/nvidia/rag-blueprint/references/deploy/helm.md b/optional-skills/mlops/nvidia/rag-blueprint/references/deploy/helm.md new file mode 100644 index 0000000000000..b381f4dcc0ad0 --- /dev/null +++ b/optional-skills/mlops/nvidia/rag-blueprint/references/deploy/helm.md @@ -0,0 +1,103 @@ +# RAG Helm Deployment + +If routed here from the deploy workflow, proceed directly to Phase 1. + +## Phase 1: Prerequisites Check + +Run all checks at once: + +```bash +echo "=== KUBECTL ===" && kubectl version --client 2>/dev/null || echo "NO_KUBECTL"; echo "=== HELM ===" && helm version --short 2>/dev/null || echo "NO_HELM"; echo "=== STORAGECLASS ===" && kubectl get storageclass 2>/dev/null || echo "NO_STORAGECLASS"; echo "=== NODES ===" && kubectl get nodes -o wide 2>/dev/null || echo "NO_CLUSTER_ACCESS"; echo "=== GPU_OPERATOR ===" && kubectl get pods -n gpu-operator 2>/dev/null | grep -i running || echo "NO_GPU_OPERATOR"; echo "=== NIM_OPERATOR ===" && kubectl get pods -n nim-operator 2>/dev/null | grep -i running || echo "NO_NIM_OPERATOR"; echo "=== NAMESPACE ===" && kubectl get namespace rag 2>/dev/null && echo "NAMESPACE_EXISTS" || echo "NO_NAMESPACE"; echo "=== HELM_RELEASE ===" && helm list -n rag 2>/dev/null | grep rag || echo "NO_EXISTING_RELEASE"; echo "=== PODS ===" && kubectl get pods -n rag 2>/dev/null | head -10 || echo "NO_PODS"; echo "=== NGC_KEY ===" && [ -n "$NGC_API_KEY" ] && echo "NGC_API_KEY SET" || echo "NGC_API_KEY NOT_SET"; echo "=== GPU_RESOURCES ===" && kubectl get nodes -o json 2>/dev/null | grep -o '"nvidia.com/gpu": "[0-9]*"' || echo "NO_GPU_RESOURCES" +``` + +Read `docs/support-matrix.md` for current Kubernetes, Helm, and OS version requirements. + +| Requirement | Check | +|-------------|-------| +| Kubernetes | Per `docs/support-matrix.md` | +| Helm | Per `docs/support-matrix.md` | +| NVIDIA GPU Operator | Installed and running | +| NVIDIA NIM Operator | Installed and running | +| Default StorageClass | Configured (e.g. local-path-provisioner) | +| Disk space | ≥200 GB per node | +| NGC_API_KEY | Set in environment | + +Report all missing prerequisites together so the user can fix everything in one pass. + +If NGC_API_KEY is NOT_SET: this is the one thing we must ask the user for. + +If an existing Helm release is detected: warn "Existing RAG Helm release found. Proceeding will upgrade it." Continue unless user objects. + +## Phase 2: Route to Reference + +Auto-detect the GPU variant from cluster nodes (not the local machine): + +```bash +echo "=== GPU_LABELS ===" && kubectl get nodes -o json 2>/dev/null | grep -oE '"nvidia.com/gpu.product":\s*"[^"]*"' | sort -u || echo "NO_GPU_LABELS"; echo "=== MIG ===" && kubectl get nodes -o json 2>/dev/null | grep -oE '"nvidia.com/mig.strategy":\s*"[^"]*"' || echo "NO_MIG" +``` + +Determine variant from node GPU labels: + +Route based on detection: + +- **MIG enabled** → read and follow `helm-mig.md` +- **RTX PRO 6000** → read and follow `helm-standard.md` (use the RTX values.yaml variant described there) +- **Standard (everything else)** → read and follow `helm-standard.md` + +Ask the user only if the variant is genuinely ambiguous. Default to standard deployment. + +## Phase 3: Expected Timelines + +Set expectations with the user: + +| Scenario | Duration | +|----------|----------| +| First deployment | 60–70 min (NIM cache download ~40–50 min, NIMService init ~10–15 min, pod startup ~5–10 min) | +| Subsequent deployments | 10–15 min (model caches already populated) | + +Pods in `ContainerCreating` or `Init` state for extended periods is normal — models download in the background without progress indicators. + +## Phase 4: Verification + +After deployment completes, verify: + +```bash +echo "=== PODS ===" && kubectl get pods -n rag; echo "=== NIMCACHE ===" && kubectl get nimcache -n rag; echo "=== NIMSERVICE ===" && kubectl get nimservice -n rag +``` + +Wait for all pods to reach `Running` status. Poll every 60 seconds for up to 70 minutes (first deployment involves model downloads). Show progress. + +Once pods are running, port-forward and verify health: + +```bash +kubectl port-forward -n rag service/rag-server 8081:8081 --address 0.0.0.0 & kubectl port-forward -n rag service/rag-frontend 3000:3000 --address 0.0.0.0 & sleep 3 && curl -s http://localhost:8081/v1/health?check_dependencies=true 2>/dev/null || echo "RAG_NOT_READY" +``` + +## Phase 5: Uninstall + +If the user wants to tear down: + +```bash +helm uninstall rag -n rag +kubectl delete nimcache --all -n rag +kubectl delete pvc --all -n rag +``` + +## On Success + +Tell the user: +- "RAG Blueprint is running on Kubernetes. Access the UI at http://localhost:3000 (via port-forward)." +- "Ask me to configure features (VLM, query rewriting, guardrails, etc.)" +- "Ask me to shutdown when you're done." + +## On Error + +1. Check pod status and events: `kubectl describe pod -n rag` and `kubectl get events -n rag --sort-by='.lastTimestamp' | tail -20`. +2. Read pod logs: `kubectl logs -n rag --tail 50`. +3. Read `references/troubleshoot.md` to match against common issues (PVC pending, OOM, image pull failure, port conflict). +4. Apply the fix and retry. If the fix requires data deletion (PVCs, namespace), confirm with user first. + +## Source Documentation +- `docs/support-matrix.md` — Kubernetes/Helm version requirements, GPU compatibility +- `docs/deploy-helm.md` — standard Helm deployment from NGC +- `docs/deploy-helm-from-repo.md` — Helm deployment from local repo diff --git a/optional-skills/mlops/nvidia/rag-blueprint/references/deploy/library-full.md b/optional-skills/mlops/nvidia/rag-blueprint/references/deploy/library-full.md new file mode 100644 index 0000000000000..1a386cb193e5b --- /dev/null +++ b/optional-skills/mlops/nvidia/rag-blueprint/references/deploy/library-full.md @@ -0,0 +1,43 @@ +# Library Mode (Full) + +## When to Use +- User wants programmatic Python access to RAG via `nvidia_rag` package +- User prefers code-level configuration over Docker-based servers +- User asks about library mode, Python client, or `NvidiaRAG`/`NvidiaRAGIngestor` + +## Restrictions +- Python 3.11+ (< 3.14) +- Docker still required for backend services (Milvus, NV-Ingest, Redis, optionally NIMs) +- Self-hosted NIMs require supported GPUs (see `docs/support-matrix.md`) + +## Process +1. Read `docs/python-client.md` for full API reference, configuration, and backend setup +2. Create virtual environment and install `nvidia-rag[all]` +3. Start backend services via Docker (Milvus, NV-Ingest + Redis, optionally NIMs) +4. Load config from `notebooks/config.yaml` using `NvidiaRAGConfig.from_yaml()` +5. Create `NvidiaRAGIngestor` and `NvidiaRAG` instances +6. Use `ingestor.create_collection()`, `ingestor.upload_documents()`, `rag.generate()`, `rag.search()` + +## Decision Table + +| Goal | Source Doc | Key Action | +|------|-----------|------------| +| Self-hosted (local GPUs) | `docs/python-client.md` | Start nims.yaml + set on-prem config | +| Cloud (NVIDIA-hosted) | `docs/python-client.md` | Skip nims.yaml, override server URLs in config | +| Custom prompts | `docs/python-client.md` | Pass `prompts=` to NvidiaRAG constructor | +| Summarization | `docs/python-client.md` | `generate_summary=True` in upload_documents | + +## Agent-Specific Notes +- Config file: `notebooks/config.yaml`; env file: `notebooks/.env_library` +- Docker login is interactive — tell user to run `docker login nvcr.io` themselves +- For cloud deployment: override `config.embeddings.server_url`, `config.llm.server_url`, etc. in code +- Config changes take effect immediately (no container restart needed, unlike Docker mode) +- Prompt customization via constructor: `NvidiaRAG(config=config, prompts="custom_prompts.yaml")` +- `upload_documents()` is async — returns `task_id` for status polling +- NV-Ingest cloud endpoints must be exported before starting NV-Ingest container + +## Notebooks +- `notebooks/rag_library_usage.ipynb` — complete walkthrough: setup, ingestion, querying, search, summaries + +## Source Documentation +- `docs/python-client.md` — full API reference, backend setup, configuration, cloud/self-hosted options diff --git a/optional-skills/mlops/nvidia/rag-blueprint/references/deploy/library-lite.md b/optional-skills/mlops/nvidia/rag-blueprint/references/deploy/library-lite.md new file mode 100644 index 0000000000000..bf7da904157d8 --- /dev/null +++ b/optional-skills/mlops/nvidia/rag-blueprint/references/deploy/library-lite.md @@ -0,0 +1,37 @@ +# Library Mode (Lite / Containerless) + +## When to Use +- Quick prototyping with zero infrastructure (no Docker, no GPU) +- User wants the fastest path to try RAG +- CI/CD pipelines needing lightweight RAG testing + +## Restrictions +- No image/table/chart citations +- No document summarization +- Subject to NVIDIA API rate limits (cloud-hosted inference) +- Requires Python 3.11+ (< 3.14), internet access, and `NGC_API_KEY` + +## Process +1. Read `docs/python-client.md` for full library mode documentation +2. Create virtualenv and install: `pip install nvidia-rag[all]` +3. Ensure `NGC_API_KEY` is exported — maps to `NVIDIA_API_KEY` internally +4. Run the lite notebook: `jupyter lab notebooks/rag_library_lite_usage.ipynb` + +## Agent-Specific Notes +- `NVIDIA_API_KEY` (used by `nvidia_rag` package) must be set from `NGC_API_KEY`: `os.environ["NVIDIA_API_KEY"] = os.environ.get("NGC_API_KEY", "")` +- Lite config lives in `notebooks/config.yaml`; override `server_url` for embeddings to the NVIDIA API Catalog endpoint (see `docs/python-client.md` for current URL), and set LLM/ranking URLs to empty string for cloud defaults +- Milvus Lite runs embedded (no container), NV-Ingest runs as subprocess (no container) +- Also install `python-dotenv jupyterlab` for notebook support + +## When Not to Use +- Production workloads — use Docker or Kubernetes +- Large-scale ingestion — rate limits apply +- Need citations from images/tables/charts or document summarization + +## Notebooks +| Notebook | Description | +|----------|-------------| +| `notebooks/rag_library_lite_usage.ipynb` | End-to-end lite mode: collection creation, ingestion, querying, search | + +## Source Documentation +- `docs/python-client.md` -- full library mode documentation (lite and full) diff --git a/optional-skills/mlops/nvidia/rag-blueprint/references/deploy/library.md b/optional-skills/mlops/nvidia/rag-blueprint/references/deploy/library.md new file mode 100644 index 0000000000000..a5162be7a1abf --- /dev/null +++ b/optional-skills/mlops/nvidia/rag-blueprint/references/deploy/library.md @@ -0,0 +1,54 @@ +# RAG Library Mode Setup + +## Determine Mode + +If routed here from the deploy workflow, the mode (full or lite) may already be decided. Use it. + +If invoked directly, auto-detect: + +```bash +echo "=== DOCKER ===" && docker --version 2>/dev/null || echo "NO_DOCKER"; echo "=== GPU ===" && nvidia-smi --query-gpu=name --format=csv,noheader 2>/dev/null || echo "NO_GPU"; echo "=== PYTHON ===" && python3 --version 2>/dev/null || echo "NO_PYTHON"; echo "=== PKG_MANAGER ===" && which uv 2>/dev/null && echo "UV_AVAILABLE" || (which pip3 2>/dev/null && echo "PIP_AVAILABLE" || echo "NO_PKG_MANAGER"); echo "=== VENV ===" && ls -d .venv/ venv/ nvidia-rag-env/ 2>/dev/null || echo "NO_EXISTING_VENV"; echo "=== INSTALLED ===" && pip3 show nvidia_rag 2>/dev/null | head -3 || echo "NOT_INSTALLED" +``` + +- Docker available → **full** (Python API + Docker backend services) +- No Docker or user explicitly says "lite" / "no docker" / "containerless" → **lite** + +Auto-route based on Docker availability. Only ask if both modes are equally valid. + +## Verify NGC_API_KEY + +Auto-check all locations: + +```bash +if [ -n "$NGC_API_KEY" ]; then echo "NGC_KEY_SET"; elif [ -n "$NVIDIA_API_KEY" ]; then echo "NVIDIA_KEY_SET"; else echo "NOT_SET"; fi +``` + +If NOT_SET: ask the user. Otherwise proceed silently. + +## Deploy + +Based on the mode: + +- **Full**: read and follow `library-full.md` +- **Lite**: read and follow `library-lite.md` + +## On Success + +Tell the user: +- Which mode was set up and how to start using it (notebook or Python script) +- "Ask me to configure features, change models, etc." +- "Ask me to shutdown backend services when done (if full mode)." + +## On Error + +1. Read the error output (pip install failure, import error, service connection error). +2. Read `references/troubleshoot.md` to match against common issues. +3. Common fixes to try: + - `pip install` failure → try `uv pip install` or check Python version ≥3.11. + - Import error → check if virtual environment is activated. + - Connection error to backend services → check Docker containers are running. +4. Retry the failed step after fixing. +5. If still failing, report the specific error to the user. + +## Source Documentation +- `docs/python-client.md` — Python library API, installation, full and lite mode setup diff --git a/optional-skills/mlops/nvidia/rag-blueprint/references/shutdown.md b/optional-skills/mlops/nvidia/rag-blueprint/references/shutdown.md new file mode 100644 index 0000000000000..7407b63d8be81 --- /dev/null +++ b/optional-skills/mlops/nvidia/rag-blueprint/references/shutdown.md @@ -0,0 +1,128 @@ +# RAG Shutdown + +Stopping containers and processes does not require confirmation. Deleting data (volumes, cache, images) does. + +## Step 1: Detect What Is Running + +Detect all deployment modes — Docker, K8s, and library: + +```bash +echo "=== DOCKER ===" && docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Image}}" 2>/dev/null || echo "NO_DOCKER"; echo "=== LIBRARY ===" && ps aux | grep -E "(nvidia_rag|uvicorn|jupyter)" | grep -v grep || echo "NO_LIBRARY_PROCESSES"; echo "=== K8S ===" && kubectl get pods -n rag 2>/dev/null | head -10 || echo "NO_K8S"; echo "=== HELM ===" && helm list -n rag 2>/dev/null | grep rag || echo "NO_HELM_RELEASE" +``` + +Based on what's detected, execute the appropriate shutdown path below. If multiple modes are active (e.g., Docker + library), stop all of them. + +## Step 2: Stop Services (Reverse Startup Order) + +Stop in this order — reverse of deployment. Only stop what is actually running (detected in Step 1). + +### 2a: Optional Services + +Stop these first if they are running: + +```bash +docker compose -f deploy/compose/docker-compose-nemo-guardrails.yaml down 2>/dev/null; docker compose -f deploy/compose/observability.yaml down 2>/dev/null +``` + +### 2b: Application Services + +```bash +docker compose -f deploy/compose/docker-compose-rag-server.yaml down; docker compose -f deploy/compose/docker-compose-ingestor-server.yaml down +``` + +### 2c: Vector DB + +```bash +docker compose -f deploy/compose/vectordb.yaml down +``` + +If using Elasticsearch instead of Milvus: +```bash +docker compose -f deploy/compose/vectordb.yaml --profile elasticsearch down +``` + +### 2d: NIMs (Self-Hosted Only) + +Only present if self-hosted deployment was used: + +```bash +docker compose -f deploy/compose/nims.yaml down +``` + +This stops ALL NIM containers (LLM, embedding, ranking, OCR, detection, and any profile-specific NIMs like VLM, audio, nemotron-parse). + +### 2e: Library Mode Processes + +If library mode is active (detected Python processes): + +```bash +pkill -f "nvidia_rag" 2>/dev/null; pkill -f "uvicorn.*rag" 2>/dev/null; docker compose -f deploy/compose/docker-compose-ingestor-server.yaml down 2>/dev/null; docker compose -f deploy/compose/vectordb.yaml down 2>/dev/null +``` + +### 2f: Kubernetes (Helm) Deployment + +If K8s deployment was detected, use the release name and namespace from `helm list` output in step 1: + +```bash +helm uninstall -n 2>/dev/null +``` + +To also clean up persistent data (only if user requests full cleanup): +```bash +kubectl delete nimcache --all -n 2>/dev/null; kubectl delete pvc --all -n 2>/dev/null +``` + +## Step 3: Verify Everything Stopped + +```bash +echo "=== REMAINING ===" && docker ps --format "table {{.Names}}\t{{.Status}}" 2>/dev/null; echo "=== K8S ===" && kubectl get pods -n rag 2>/dev/null | head -10 || echo "NOT_K8S"; helm list -n rag 2>/dev/null || true +``` + +If any RAG-related containers remain, force remove: +```bash +docker ps -a --format "{{.Names}}" | grep -E "(rag|milvus|nim|ingest|redis|nemo|grafana|prometheus|embedding|ranking|vlm|ocr|page-elements|graphic-elements|table-structure)" | xargs -r docker rm -f +``` + +If pods remain after `helm uninstall`, force delete: +```bash +kubectl delete pods --all -n rag --force --grace-period=0 2>/dev/null +``` + +## Step 4: Optional Cleanup + +Ask the user if they want to clean up data/volumes: + +- **Remove Docker volumes** (deletes ingested data, Milvus indices): + ```bash + docker volume prune -f + ``` + +- **Remove model cache** (frees 100-200 GB for self-hosted): + ```bash + rm -rf ~/.cache/model-cache/ + ``` + +- **Remove Docker images** (frees disk space): + ```bash + docker images | grep -E "nvcr.io/nvidia|milvusdb" | awk '{print $3}' | xargs -r docker rmi + ``` + +Only perform cleanup if the user explicitly requests it. + +## Quick One-Liner (All Docker Services) + +If the user wants a fast full teardown: + +```bash +cd "$(git rev-parse --show-toplevel)" && \ +docker compose -f deploy/compose/docker-compose-nemo-guardrails.yaml down 2>/dev/null; \ +docker compose -f deploy/compose/observability.yaml down 2>/dev/null; \ +docker compose -f deploy/compose/docker-compose-rag-server.yaml down 2>/dev/null; \ +docker compose -f deploy/compose/docker-compose-ingestor-server.yaml down 2>/dev/null; \ +docker compose -f deploy/compose/vectordb.yaml down 2>/dev/null; \ +docker compose -f deploy/compose/nims.yaml down 2>/dev/null; \ +echo "All RAG services stopped." +``` + +## Source Documentation +- `docs/troubleshooting.md` — if services won't stop or containers hang diff --git a/optional-skills/mlops/nvidia/rag-blueprint/references/troubleshoot.md b/optional-skills/mlops/nvidia/rag-blueprint/references/troubleshoot.md new file mode 100644 index 0000000000000..bf0308f8ba3e8 --- /dev/null +++ b/optional-skills/mlops/nvidia/rag-blueprint/references/troubleshoot.md @@ -0,0 +1,146 @@ +# RAG Troubleshooting + +## Auto-Triage: Run First + +Start with this diagnostic sweep: + +```bash +echo "=== CONTAINERS ===" && docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}" 2>/dev/null | grep -E "(rag|milvus|nim|ingest|redis|etcd|minio)" | head -20; echo "=== HEALTH ===" && curl -s http://localhost:8081/v1/health?check_dependencies=true 2>/dev/null || echo "RAG_UNREACHABLE"; curl -s http://localhost:8082/v1/health?check_dependencies=true 2>/dev/null || echo "INGESTOR_UNREACHABLE"; echo "=== LOGS ===" && for svc in rag-server ingestor-server nim-llm-ms nemoretriever-embedding-ms nemoretriever-ranking-ms; do echo "--- $svc ---"; docker logs --tail 20 "$svc" 2>/dev/null | grep -iE "(error|fail|exception|timeout|oom)" || echo "OK"; done; echo "=== GPU ===" && nvidia-smi 2>/dev/null | head -20 || echo "NO_GPU"; echo "=== DISK ===" && df -h / | tail -1; echo "=== DOCKER_DISK ===" && docker system df 2>/dev/null; echo "=== K8S ===" && kubectl get pods -n rag 2>/dev/null | head -20 || echo "NOT_K8S" +``` + +Analyze all output, then diagnose and fix. If Auto-Triage doesn't reveal the cause, dig deeper into the specific failing service's logs (`docker logs --tail 100` or `kubectl logs -n rag --tail 100`). + +Confirm with the user before deleting data (volumes, collections, model cache), changing deployment mode, or modifying API keys. + +## Source Documentation for Detailed Diagnosis + +Read these docs to find specific issue descriptions, causes, and fixes: + +- `docs/troubleshooting.md` — primary reference: all common issues with detailed symptoms/fixes +- `docs/debugging.md` — Pipeline debugging: monitoring deployment, verifying endpoints, tracing requests +- `docs/service-port-gpu-reference.md` — Complete port/GPU mapping table for all services + +## Expected Deployment Times + +If user reports "deployment is taking too long," compare against these baselines: + +| Mode | First Run | Subsequent | +|------|-----------|------------| +| Docker (self-hosted) | 15--30 min (model downloads) | 2--5 min | +| Docker (NVIDIA-hosted) | 5--10 min (no model downloads) | 1--2 min | +| K8s/Helm | 60--70 min (NIM cache 40--50 min + init 10--15 min + pod startup 5--10 min) | 10--15 min | + +If deployment exceeds these times, check NIM container logs: `docker logs nim-llm-ms --tail 50` and model cache disk usage: `watch -n 10 'du -sh ~/.cache/model-cache/'`. + +## Service Health Endpoints + +Read `docs/service-port-gpu-reference.md` for the complete port/GPU mapping. Quick check: + +| Service | URL | Expected | +|---------|-----|----------| +| RAG Server | `http://localhost:8081/v1/health?check_dependencies=true` | `{"status":"healthy"}` | +| Ingestor | `http://localhost:8082/v1/health?check_dependencies=true` | `{"status":"healthy"}` | +| NV-Ingest | `http://localhost:7670/v1/health/ready` | 200 OK | +| Embedding NIM | `http://localhost:9080/v1/health/ready` | 200 OK | +| LLM NIM | `http://localhost:8999/v1/health/ready` | 200 OK | +| Ranking NIM | `http://localhost:1976/v1/health/ready` | 200 OK | +| Milvus | `http://localhost:9091/healthz` | 200 OK | + +## Kubernetes Monitoring Commands + +```bash +kubectl get nimcache -n rag +kubectl get pods -n rag +kubectl logs -f -n rag +kubectl get pvc -n rag +kubectl get events -n rag --sort-by='.lastTimestamp' +``` + +Pods in `ContainerCreating` or `Init` state during model download is expected. Use `kubectl get nimcache -n rag -w` to watch download progress. + +## Enable Debug Logging + +```bash +export LOGLEVEL=DEBUG +docker compose -f deploy/compose/docker-compose-ingestor-server.yaml up -d --no-deps ingestor-server +docker compose -f deploy/compose/docker-compose-rag-server.yaml up -d --no-deps rag-server +``` + +--- + +## Symptom-to-Fix Quick Index + +Match the symptom from Auto-Triage output, then read `docs/troubleshooting.md` for the detailed fix. For pipeline debugging steps, read `docs/debugging.md`. + +| Symptom | Category | Quick Fix | +|---------|----------|-----------| +| NIM container stuck at `(health: starting)` >30min | NIM Startup | Check GPU memory, NGC auth, disk space. First-run model downloads are slow — wait and monitor cache size. | +| Milvus unhealthy / search returns nothing | Milvus | Restart vectordb compose. Check etcd/MinIO. Port 19530 conflict. Corrupt data → `down -v` (destroys data). | +| Document upload fails / ingestor health check fails | NV-Ingest | Check Redis, OCR NIMs. Rate limit (429) → reduce batch vars. Large PDFs → reduce batch size. | +| Chat returns errors / /generate fails | RAG Server | Check LLM NIM health, embedding NIM, cloud API key. Verify `APP_LLM_MODELNAME` matches deployed NIM. | +| DNS resolution failed for `:` | Networking | Service container not running. Check `docker ps`, restart missing service. | +| Port already in use | Networking | `lsof -i :` to find conflicting process. See port table above. | +| GPU out of memory / `torch.OutOfMemoryError` | GPU | Kill other GPU processes, use `--profile rag` for fewer NIMs, or set correct `NIM_MODEL_PROFILE`. | +| `nvidia-container-cli: unknown device` | GPU | GPU ID exceeds available GPUs. Run `nvidia-smi -L`, adjust `*_GPU_ID` vars to valid IDs. | +| Disk full / insufficient space | Disk | `docker system prune -f`, remove unused images, check model cache size. | +| `no configuration file provided: not found` | Docker Compose | Run from the repo root directory. | +| `too many open files` | Docker Compose | Set `LimitNOFILE=65536` in containerd override, restart containerd. | +| PVC stuck in Pending | Helm | Create missing StorageClass or update PVC. | +| `ProvisioningFailed` access mode mismatch | Helm | Patch NIMCache to `ReadWriteOnce`. | +| Ingestor OOMKilled | Helm | Increase memory limits in values.yaml. Set `SUMMARY_MAX_PARALLELIZATION=1`. | +| Elasticsearch timeout during ingestion | Elasticsearch | Increase `ES_REQUEST_TIMEOUT` (default 600s). | +| Hallucination / out-of-context responses | Quality | Add missing-info handling to prompt in `prompt.yaml`. | +| Embedding dimensions mismatch | Models | Set `APP_EMBEDDINGS_DIMENSIONS` to match model output. Re-ingest. | +| Hybrid/dense search type mismatch | Search | Align `APP_VECTORSTORE_SEARCHTYPE` on ingestor and rag-server. Re-ingest. | +| Confidence threshold filtering all results | Search | Lower `RERANKER_SCORE_THRESHOLD` (range 0.0–1.0, default 0.0). | +| OCR not starting / connection errors | OCR | Check GPU memory, NGC auth. Verify `OCR_GRPC_ENDPOINT`/`OCR_HTTP_ENDPOINT` match running service. | +| NVIDIA API credits exhausted | Cloud | Contact NVIDIA representative for additional credits. | +| Image-only PDFs not ingesting | Ingestion | Enable `APP_NVINGEST_EXTRACTINFOGRAPHICS`. Consider image captioning. | + +--- + +## Troubleshooting Checklists + +### Ingestion Checklist +- [ ] All required containers running (ingestor-server, nv-ingest-ms-runtime, milvus, redis) +- [ ] Vector database accessible (`curl http://localhost:9091/healthz`) +- [ ] Embedding service healthy (`curl http://localhost:9080/v1/health/ready`) +- [ ] File format supported and size <= 400 MB +- [ ] Sufficient disk space (`df -h /`) +- [ ] GPU resources available (`nvidia-smi`) + +### Retrieval Checklist +- [ ] RAG server running and healthy +- [ ] LLM service accessible (`curl http://localhost:8999/v1/health/ready`) +- [ ] Vector database contains data (collection exists with documents) +- [ ] Collection name is correct +- [ ] Query format is valid + +### Quality Checklist +- [ ] Reranker is enabled and healthy +- [ ] Top-K values are appropriate +- [ ] Collection has sufficient relevant data +- [ ] Query rewriting configured correctly +- [ ] Prompt template appropriate for use case + +--- + +## Full Reset + +Destroys all data (volumes, images, caches). Confirm with the user before running. + +If nothing else works and the user confirms: + +```bash +cd "$(git rev-parse --show-toplevel)" +docker compose -f deploy/compose/docker-compose-nemo-guardrails.yaml down 2>/dev/null +docker compose -f deploy/compose/observability.yaml down 2>/dev/null +docker compose -f deploy/compose/docker-compose-rag-server.yaml down 2>/dev/null +docker compose -f deploy/compose/docker-compose-ingestor-server.yaml down 2>/dev/null +docker compose -f deploy/compose/vectordb.yaml down -v 2>/dev/null +docker compose -f deploy/compose/nims.yaml down 2>/dev/null + +docker system prune -af --volumes +``` + +Then deploy fresh using the deploy workflow. diff --git a/tests/tools/test_ast_search.py b/tests/tools/test_ast_search.py new file mode 100644 index 0000000000000..b199280a704bb --- /dev/null +++ b/tests/tools/test_ast_search.py @@ -0,0 +1,78 @@ +#!/usr/bin/env python3 +""" +Unit tests for the AST Search tool module in hermes-agent (ported from Cortex Agent). +""" + +import pytest +from pathlib import Path +from tools.ast_search import ast_search_tool, _parse_file_ast, check_ast_search_requirements +from tools.registry import registry + + +def test_ast_search_requirements(): + assert check_ast_search_requirements() is True + + +def test_ast_search_tool_nonexistent_path(): + res = ast_search_tool(path="/non/existent/path/file.py") + assert "does not exist" in res.lower() or "error" in res.lower() + + +def test_ast_search_tool_non_python_file(tmp_path): + txt_file = tmp_path / "test.txt" + txt_file.write_text("Hello World", encoding="utf-8") + res = ast_search_tool(path=str(txt_file)) + assert "supported on python" in res.lower() + + +def test_ast_search_tool_single_file(tmp_path): + code = ''' +import os +import json + +class Calculator: + """A simple calculator class.""" + def add(self, a, b): + return a + b + +async def fetch_data(url): + """Fetch data asynchronously.""" + pass +''' + py_file = tmp_path / "sample.py" + py_file.write_text(code, encoding="utf-8") + + # Test all symbols + res_all = ast_search_tool(path=str(py_file), symbol_type="all") + assert "Calculator" in res_all + assert "add" in res_all + assert "fetch_data" in res_all + assert "os" in res_all + + # Test class filtering + res_class = ast_search_tool(path=str(py_file), symbol_type="class") + assert "Calculator" in res_class + assert "fetch_data" not in res_class + + # Test query filtering + res_query = ast_search_tool(path=str(py_file), query="fetch") + assert "fetch_data" in res_query + assert "Calculator" not in res_query + + +def test_ast_search_tool_directory(tmp_path): + dir_path = tmp_path / "src" + dir_path.mkdir() + (dir_path / "mod1.py").write_text("class ModuleOne:\n pass\n", encoding="utf-8") + (dir_path / "mod2.py").write_text("def module_two_fn():\n pass\n", encoding="utf-8") + + res = ast_search_tool(path=str(dir_path)) + assert "ModuleOne" in res + assert "module_two_fn" in res + + +def test_ast_search_registered_in_registry(): + entry = registry.get_entry("ast_search") + assert entry is not None + assert entry.name == "ast_search" + assert entry.toolset == "ast_search" diff --git a/tools/ast_search.py b/tools/ast_search.py new file mode 100644 index 0000000000000..eeb9c55871b50 --- /dev/null +++ b/tools/ast_search.py @@ -0,0 +1,205 @@ +#!/usr/bin/env python3 +""" +AST Search Tool Module - Structural Code Symbol Navigator + +Ported from Cortex Agent's high-efficiency AST symbol navigator engine. +Parses Abstract Syntax Trees across Python source files to extract class definitions, +method signatures, function contracts, docstrings, and import hierarchies cleanly +without requiring full-file context dumping. + +Design: +- Single `ast_search` tool: supply `path`, optional `symbol_type` and `query` +- Zero external dependencies (uses standard library `ast` module) +- Returns structured Markdown tables & code slice representations +- Reduces LLM token usage by up to 88% on codebase inspection +""" + +import ast +import os +from pathlib import Path +from typing import Dict, Any, List, Optional + +AST_SEARCH_SCHEMA = { + "type": "function", + "function": { + "name": "ast_search", + "description": ( + "Parse Python Abstract Syntax Tree (AST) structure of a file or directory. " + "Extracts classes, methods, functions, docstrings, and imports cleanly " + "without dumping full file contents, saving context window tokens. " + "Ported from Cortex Agent's symbol navigator engine." + ), + "parameters": { + "type": "object", + "properties": { + "path": { + "type": "string", + "description": "Path to Python source file or directory to inspect." + }, + "symbol_type": { + "type": "string", + "enum": ["all", "class", "function", "method", "import"], + "description": "Filter by specific symbol type (default: 'all').", + "default": "all" + }, + "query": { + "type": "string", + "description": "Optional substring query to search within symbol names.", + "default": "" + } + }, + "required": ["path"] + } + } +} + + +def check_ast_search_requirements() -> bool: + """AST search relies purely on Python standard library modules.""" + return True + + +def _parse_file_ast(file_path: Path, symbol_type: str = "all", query: str = "") -> List[Dict[str, Any]]: + symbols = [] + try: + content = file_path.read_text(encoding="utf-8", errors="replace") + tree = ast.parse(content, filename=str(file_path)) + except Exception as e: + return [{"type": "error", "file": str(file_path), "name": str(e), "line": 0}] + + query_lower = query.lower() + + for node in ast.walk(tree): + # Class definitions + if isinstance(node, ast.ClassDef): + if symbol_type in ("all", "class"): + if not query or query_lower in node.name.lower(): + doc = ast.get_docstring(node) or "" + bases = [b.id for b in node.bases if isinstance(b, ast.Name)] + methods = [n.name for n in node.body if isinstance(n, (ast.FunctionDef, ast.AsyncFunctionDef))] + symbols.append({ + "type": "class", + "name": node.name, + "line": node.lineno, + "file": str(file_path), + "bases": bases, + "methods": methods, + "docstring": doc.split("\n")[0] if doc else "" + }) + + # Function & Method definitions + elif isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)): + if symbol_type in ("all", "function", "method"): + if not query or query_lower in node.name.lower(): + doc = ast.get_docstring(node) or "" + args = [a.arg for a in node.args.args] + is_async = isinstance(node, ast.AsyncFunctionDef) + symbols.append({ + "type": "async_function" if is_async else "function", + "name": node.name, + "line": node.lineno, + "file": str(file_path), + "args": args, + "docstring": doc.split("\n")[0] if doc else "" + }) + + # Imports + elif isinstance(node, (ast.Import, ast.ImportFrom)) and symbol_type in ("all", "import"): + if isinstance(node, ast.Import): + for alias in node.names: + if not query or query_lower in alias.name.lower(): + symbols.append({ + "type": "import", + "name": alias.name, + "line": node.lineno, + "file": str(file_path) + }) + elif isinstance(node, ast.ImportFrom): + mod = node.module or "" + for alias in node.names: + full_name = f"{mod}.{alias.name}" if mod else alias.name + if not query or query_lower in full_name.lower(): + symbols.append({ + "type": "import", + "name": full_name, + "line": node.lineno, + "file": str(file_path) + }) + + return symbols + + +def ast_search_tool(path: str, symbol_type: str = "all", query: str = "") -> str: + """Handler for the ast_search tool.""" + from tools.registry import tool_error + + if not path: + return tool_error("Path parameter is required.") + + target_path = Path(path).resolve() + if not target_path.exists(): + return tool_error(f"Path does not exist: {path}") + + files_to_parse: List[Path] = [] + if target_path.is_file(): + if target_path.suffix == ".py": + files_to_parse.append(target_path) + else: + return tool_error(f"AST search is supported on Python (.py) files: {path}") + elif target_path.is_dir(): + for root, _, files in os.walk(target_path): + for f in files: + if f.endswith(".py"): + files_to_parse.append(Path(root) / f) + + if not files_to_parse: + return "No Python (.py) files found to parse." + + all_symbols: List[Dict[str, Any]] = [] + for fpath in files_to_parse[:50]: # Cap to 50 files max for safety + all_symbols.extend(_parse_file_ast(fpath, symbol_type=symbol_type, query=query)) + + if not all_symbols: + return f"No AST symbols matched query '{query}' (symbol_type: {symbol_type})." + + output_lines = [f"### 🔍 AST Symbol Search Results ({len(all_symbols)} symbols found)"] + output_lines.append("| Type | Name | Location | Info |") + output_lines.append("| :--- | :--- | :--- | :--- |") + + for sym in all_symbols[:100]: # Cap output table + stype = sym.get("type", "symbol") + sname = sym.get("name", "") + sline = sym.get("line", 0) + sfile = Path(sym.get("file", "")).name + + info = "" + if stype == "class": + bases = sym.get("bases", []) + methods = sym.get("methods", []) + info = f"Bases: {', '.join(bases) if bases else 'None'} | Methods: {len(methods)}" + elif "function" in stype: + args = sym.get("args", []) + info = f"Args: ({', '.join(args[:5])})" + elif stype == "import": + info = "Import statement" + + output_lines.append(f"| `{stype}` | **{sname}** | `{sfile}:{sline}` | {info} |") + + return "\n".join(output_lines) + + +# --- Registry --- +from tools.registry import registry + +registry.register( + name="ast_search", + toolset="ast_search", + schema=AST_SEARCH_SCHEMA, + handler=lambda args, **kw: ast_search_tool( + path=args.get("path", ""), + symbol_type=args.get("symbol_type", "all"), + query=args.get("query", "") + ), + check_fn=check_ast_search_requirements, + emoji="🔍", +)