From 0d5854ff59b44f27a73bc374560bb8ad61c279e8 Mon Sep 17 00:00:00 2001 From: adi0106 <119348849+adi0106@users.noreply.github.com> Date: Mon, 30 Mar 2026 14:24:15 -0700 Subject: [PATCH] Adding launchable notbook needs to be on a public github to deploy on brev --- cuopt-agent/cuopt-agent-launchable.ipynb | 213 +++++++++++++++++++++++ 1 file changed, 213 insertions(+) create mode 100644 cuopt-agent/cuopt-agent-launchable.ipynb diff --git a/cuopt-agent/cuopt-agent-launchable.ipynb b/cuopt-agent/cuopt-agent-launchable.ipynb new file mode 100644 index 0000000..29b780e --- /dev/null +++ b/cuopt-agent/cuopt-agent-launchable.ipynb @@ -0,0 +1,213 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "6ca53b07-b2e2-4f4b-8e81-71261d4a4310", + "metadata": {}, + "source": [ + "# cuOpt Agent\n", + "\n", + "The cuOpt Agent is a reference optimization assistant that translates natural-language problem descriptions into mathematical models, solves them on the GPU with NVIDIA cuOpt, and returns explained results. It ships with a multi-period supply chain planning scenario (max-supply) as its built-in use case, but the architecture is designed to be extended to other LP/MILP domains by adding new skills, data files, and configs. It is built as a LangChain Deep Agents workflow on top of NAT, with structured skills that make the path from problem text to correct formulation more reliable. The agent uses an orchestrator-subagent pattern: the orchestrator receives user queries and delegates optimization work to a specialized cuOpt subagent via the task() tool, keeping coordination logic separate from problem-solving logic.\n", + "\n", + "Key features:\n", + "\n", + "- GPU-accelerated solver: cuOpt LP/MILP solver for fast optimization on NVIDIA GPUs.\n", + "- Structured skills: Parsing, modeling, debugging, and supply-chain planning skills give the agent rules and reference models so it formulates correctly on the first try.\n", + "- Mandatory ambiguity handling: When problem text is ambiguous, the agent must clarify or solve all plausible interpretations.\n", + "- YAML-driven configuration: Agents, LLMs, and workflows are defined in config files; tune behavior without code changes.\n", + "- Web UI: Chat interface for interacting with the agent.\n", + "- Tracing: Phoenix and LangSmith (optional) for inspecting agent behavior.\n", + "- Evaluation harness: Built-in eval configs for measuring agent quality.\n", + "\n", + "### Software Components\n", + "\n", + "| Component | Purpose |\n", + "|-----------|---------|\n", + "| [NVIDIA NeMo Agent Toolkit](https://docs.nvidia.com/nemo/agent-toolkit/latest/) | Agent framework and serving |\n", + "| [NVIDIA cuOpt](https://developer.nvidia.com/cuopt) | GPU-accelerated LP/MILP solver |\n", + "| [LangChain Deep Agents](https://www.langchain.com/) | Multi-step agent workflow |\n", + "| [minimaxai/minimax-m2.5](https://build.nvidia.com/) (via NIM) | LLM for agent reasoning |\n", + "| [Phoenix](https://github.com/Arize-ai/phoenix) | OpenTelemetry tracing |\n", + "| [LangSmith](https://smith.langchain.com/) (optional) | Agent tracing and observability |\n", + "| [NAT UI](external/nat-ui/) | Chat web interface |\n", + "\n", + "\n", + "### Prerequisites\n", + "\n", + "- NVIDIA GPU with CUDA support\n", + "- Docker and Docker Compose (with [NVIDIA Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html))\n", + "- Access to `nvcr.io/nvidia/cuopt/cuopt:26.2.0-cuda12.9-py3.13` base image ([NGC](https://catalog.ngc.nvidia.com/))\n", + "- NVIDIA API key from [build.nvidia.com](https://build.nvidia.com/)\n", + "\n", + "Since you are running this in a Brev launchable environment, CUDA and Docker prereqs are taken care of. Before running through this notebook, ensure you have access to the cuOpt image and that you have an API key. \n", + "\n", + "**Optional:**\n", + "\n", + "- [LangSmith](https://smith.langchain.com/) API key for agent tracing (uncomment the LangSmith section in the config YAML to enable)\n", + "\n", + "\n", + "**For local development (without Docker) and improved performance**\n", + "Check the guide [here](https://github.com/NVIDIA/cuopt-examples/tree/main/cuopt-agent#readme)" + ] + }, + { + "cell_type": "markdown", + "id": "2e448b92-7e22-4c22-a589-77e22497ac19", + "metadata": {}, + "source": [ + "## 1. Clone the Repository\n", + "First, we will clone the cuOpt examples repostory, which has sample notebooks for a wide variety of use cases. The subdirectory `cuopt-agent` includes all the code needed for this demo. \n", + "Let's clone the repo and move into the relevant subdirectory." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "c72e623b-2b22-4359-963e-538d9178f6f2", + "metadata": {}, + "outputs": [], + "source": [ + "!git clone https://github.com/NVIDIA/cuopt-examples.git" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "d020093b-807c-4b2a-bfbb-05e9ea809380", + "metadata": {}, + "outputs": [], + "source": [ + "%cd cuopt-examples/cuopt-agent" + ] + }, + { + "cell_type": "markdown", + "id": "8af68370-a96d-4fea-95cc-a85237d6837c", + "metadata": {}, + "source": [ + "## 2. Quick Start\n", + "Let's initialize a couple submodules and environment variables." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "2da20b4a-d499-4589-8dd1-f802fba01471", + "metadata": {}, + "outputs": [], + "source": [ + "# paste here your API key from build.nvidia.com\n", + "import os\n", + "os.environ['NVIDIA_API_KEY'] = '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'" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "0135cbf7-a454-4527-b343-01ee074961e3", + "metadata": {}, + "outputs": [], + "source": [ + "# 1. Initialize submodules (required for the Chat UI)\n", + "! git submodule update --init --recursive\n", + "\n", + "# 2. Set up environment variables\n", + "!cp .env.example .env\n", + "\n", + "# save the API Key to the .env file\n", + "with open(\".env\", \"a\") as f:\n", + " f.write(f\"\\nNGC_API_KEY={os.environ['NVIDIA_API_KEY']}\\n\")\n", + "\n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "8c9e5dba-220b-4de0-9f87-f6359a169972", + "metadata": {}, + "outputs": [], + "source": [ + "# log in to NVIDIA container registry so we can access the cuOpt container\n", + "! docker login nvcr.io --username '$oauthtoken' --password {os.environ['NVIDIA_API_KEY']}" + ] + }, + { + "cell_type": "markdown", + "id": "ca82f81f-be96-4ae4-837c-f81a47a3a8f7", + "metadata": {}, + "source": [ + "Before building and running the demo, there are two fixes we need to make. These will be fixed in the next version of the Launchable.\n", + "1. in cuopt-examples/cuopt-agent/external/nat-ui/proxy/request-transformers.js, replace the llm `nvidia/nemotron` with `minimaxai/minimax-m2.5` on lines 81 and 120.\n", + "2. in cuopt-examples/cuopt-agent/cuopt_agent/configs/config-deepagent.yml, replace `${NVIDIA_API_KEY}` with your actual API Key 'nvapi-***' on line 45." + ] + }, + { + "cell_type": "markdown", + "id": "8f00dc09-394b-4b51-8daf-bf0e20f07ff1", + "metadata": {}, + "source": [ + "## 3. Build and start all services\n", + "\n", + "We are ready to build and run the demo. Note that each one of the following commands may take a couple minutes to run. " + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "8dff04cb-75d6-4ed8-8ced-c8388b9ebcc5", + "metadata": { + "scrolled": true + }, + "outputs": [], + "source": [ + "! docker compose -f deploy/compose/docker-compose.yml build" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "2f7e58c0-878c-459c-8bec-248735c30f97", + "metadata": { + "scrolled": true + }, + "outputs": [], + "source": [ + "! docker compose -f deploy/compose/docker-compose.yml up -d" + ] + }, + { + "cell_type": "markdown", + "id": "59d858ea-edcb-40e9-a96c-c41313cce86d", + "metadata": {}, + "source": [ + "## 4. open the Chat UI and Phoenix Tracing. \n", + "\n", + "Go back to the Brev Launchable page, and in the `Using Secure Links` sections add port 3000 for Chat UI and port 6006 for Phoenix tracing. Then click the arrow buttons to launch in browser.\n", + "\n", + "There are sample prompts you can copy and paste in the UI in `cuopt-examples/cuopt-agent/cuopt_agent/data/max_supply_what_ifs/sample_prompts`.\n", + "\n" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python 3 (ipykernel)", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.12.13" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +}