optimization-mode-router

name	optimization-mode-router
version	26.06.01
description	Choose fast direct-to-cuOpt solve versus replayable or auditable model artifact mode.
license	Apache-2.0
metadata	{"author":"NVIDIA cuOpt Team","tags":["cuopt","nemoclaw","orchestration"]}
origin	skill-evolution

Optimization Mode Router

Use this skill when a user asks a question that may be answered by solving an optimization problem from uploaded or provided data, and you need to decide whether to:

• proceed with a fast direct-to-cuOpt solve, or
• offer a replayable/auditable path that preserves a structured model artifact for later reruns, review, export, or audit.

This skill is about mode selection, not full formulation. Its purpose is to keep the common path fast while surfacing stronger reproducibility only when it is actually useful.

Read this when

Read this skill when all of the following are true:

1. The user appears to be asking a question that could become an LP, MILP, QP, or routing problem.
2. The user has provided data, or is expected to provide data.
3. You need to decide whether to:
   • go straight to a direct cuOpt solve, or
   • preserve a replayable/auditable artifact as part of the workflow.

Do not use this skill for

• Pure formulation work after the execution mode has already been chosen.
• Pure cuOpt API usage when the user has already clearly chosen fast vs replayable mode.
• Non-optimization analytics questions.

Default behavior

• Default to Fast mode.
• Default to direct cuOpt solve for one-off requests from uploaded CSVs (schedule, assignment, allocation, routing) — proceed to cuopt-model-mapper without asking fast vs replayable unless the user signals audit/export/rerun.
• Do not ask about replayability/auditability unless there is a real signal that it matters.
• Avoid turning a straightforward optimization request into a heavy upfront questionnaire.
• NemoClaw sandbox: Fast mode means cuOpt after cuopt-sandbox gates — never a custom greedy/heuristic builder as the solve path.

Two modes

Fast mode

Use Fast mode when the user appears to want the quickest route to an answer.

Behavior:

• inspect the provided data
• identify whether the request is LP, MILP, QP, or routing
• ask only the minimum necessary clarifying questions
• build the model directly in cuOpt
• solve and explain the result
• do not preserve a replayable model artifact unless requested

Replayable / Auditable mode

Use this mode when the user wants reuse, traceability, or formal review.

Behavior:

• capture explicit assumptions
• record data-to-model mappings
• preserve a structured model specification or equivalent reusable artifact
• solve with cuOpt
• return both the answer and reusable/reviewable model metadata

When to ask the mode-selection question

Ask the user to choose between Fast mode and Replayable/Auditable mode if any of the following are true:

1. The user explicitly asks for any of these:

   • save the model
   • rerun on new data
   • replay later
   • recurring or scheduled runs
   • audit trail
   • export the model
   • document assumptions
   • review the formulation
   • show how the data maps into the model

2. The request appears operational or recurring rather than one-off:

   • daily / weekly / monthly planning
   • production workflow
   • repeated scenario analysis
   • future datasets are expected

3. The user indicates a need for traceability or justification:

   • compliance
   • internal or external review
   • reproducibility
   • explicit explanation of assumptions or mappings

When not to ask

Do not ask the mode-selection question when the request is clearly:

• one-off
• exploratory
• ad hoc
• speed-oriented

In those cases, proceed in Fast mode unless the user later asks for replayability, audit, export, or model persistence.

Recommended user-facing phrasing

Preferred short form:

Should I treat this as a one-off solve, or make it replayable/auditable too?

Alternative longer form:

I can do this in two ways: Fast mode for the quickest answer, or Replayable mode that also keeps a structured spec for reruns, audit, and reuse. Which do you want?

Decision rule

• If there is no meaningful signal for replayability/auditability → use Fast mode silently.
• If there is a meaningful signal → ask the mode-selection clarifier early.
• If the user chooses replayable/auditable mode → preserve the structured artifact and proceed.
• If the user chooses fast mode → proceed directly to cuOpt.

Handoff guidance

After selecting a mode, hand off based on problem type:

• If the request is LP / MILP:

  • use numerical-optimization-formulation
  • then use cuopt-numerical-optimization-api-python (or cuopt-numerical-optimization-api-cli for MPS inputs)
  • in sandbox contexts, follow cuopt-sandbox (gates + selected gRPC path) before any LP/MILP solve

• If the request is QP:

  • use numerical-optimization-formulation
  • then use cuopt-numerical-optimization-api-python
  • in sandbox contexts, follow cuopt-sandbox (gates + selected gRPC path) before any QP solve

• If the request is routing (VRP / TSP / PDP):

  • use routing-formulation
  • then use cuopt-routing-api-python
  • in sandbox contexts, follow cuopt-sandbox (gates + REST) before any routing solve

• If the user is asking about server usage or deployment rather than solving a model directly:

  • use cuopt-server-common or cuopt-server-api-python as appropriate

• In all cuOpt user tasks:

  • follow cuopt-user-rules

Operational notes

• This skill is about execution mode selection, not full mathematical modeling.
• Keep the user experience lightweight by default.
• Prefer direct-to-cuOpt for one-off work.
• Use replayable/auditable mode only when the user’s needs justify the extra structure.