quantum-scheduling-agent

Hybrid quantum-classical autonomous agent using NVIDIA CUDA-Q and LangChain to solve NP-hard scheduling problems with QAOA Here is your complete README. We'll create it as a file then paste it into GitHub.

$code = @'
# Quantum Scheduling Agent

A hybrid quantum-classical autonomous agent that solves NP-hard class scheduling problems using the QAOA (Quantum Approximate Optimization Algorithm) on NVIDIA CUDA-Q, wrapped with a LangChain agent framework.

Built and tested on NVIDIA NGC infrastructure.

---

## Demo

The agent receives a natural language prompt, routes it to the correct tool, runs a quantum optimization circuit, and returns a conflict-free schedule — all automatically.

You: optimize the schedule [Agent] Decision: optimize_schedule tool [Agent] Running quantum optimizer... [Result logged]

========================================== BOARDING SCHOOL SCHEDULE

TIME SLOT A:

• Math (Teacher A)
• History (Teacher C)
• French (Teacher B) TIME SLOT B:
• English (Teacher B)
• Science (Teacher A)
• Technology (Teacher C)

CONFLICT CHECK: OK Teacher A: Math(A) vs Science(B) -- OK OK Teacher B: English(B) vs French(A) -- OK OK Teacher C: History(A) vs Technology(B) -- OK

STATUS: VALID SCHEDULE - 0 CONFLICTS

---

## What This Project Does

Classical computers solve scheduling problems by trying combinations one at a time. For large schedules this becomes computationally expensive fast — it is an NP-hard problem.

This project uses QAOA to explore many combinations simultaneously using quantum superposition, then uses quantum interference to amplify the best conflict-free solution. The result is passed back to a classical LangChain agent that interprets it, formats it, and logs it automatically.

This is the same class of problem that enterprise quantum systems like NVIDIA Origin Pilot and OQTOPUS are designed to solve at scale.

---

## Architecture

Natural Language Prompt | LangChain Agent (agent.py) | Quantum Tool (schedule.py) | CUDA-Q QAOA Circuit (6 qubits, 4 layers) | Conflict-Free Schedule Output + Log

---

## Problem Formulation

The scheduling problem is encoded as a graph coloring problem:

- **Nodes:** 6 classes (Math, English, Science, History, Technology, French)
- **Edges:** 3 teacher conflicts
  - Math -- Science (Teacher A)
  - English -- French (Teacher B)
  - History -- Technology (Teacher C)
- **Goal:** Assign time slots so no two connected nodes share the same slot

Each edge becomes a term in the QAOA Hamiltonian. The optimizer tunes quantum circuit parameters until the measurement distribution concentrates on conflict-free bit strings.

---

## Tech Stack

| Tool | Role |
|------|------|
| NVIDIA CUDA-Q | Quantum circuit simulation on GPU |
| QAOA Algorithm | Quantum optimization for NP-hard problems |
| LangChain | Agent framework and tool routing |
| Python 3.10 | Primary language |
| NVIDIA NGC | Cloud container infrastructure |
| Docker | Container runtime |

---

## How to Run

### Prerequisites
- Docker Desktop installed
- NVIDIA NGC account (free at ngc.nvidia.com)

### Pull the CUDA-Q container
```bash
docker pull nvcr.io/nvidia/quantum/cuda-quantum:cu12-0.9.0

Install LangChain dependencies

docker run --rm --entrypoint="" -v /your/local/path:/files \
  nvcr.io/nvidia/quantum/cuda-quantum:cu12-0.9.0 \
  python3 -m pip install langchain==0.1.20 langchain-community==0.0.38 \
  --target /files/packages --quiet

Run the quantum scheduler

docker run --rm --entrypoint="" -v /your/local/path:/files \
  nvcr.io/nvidia/quantum/cuda-quantum:cu12-0.9.0 \
  python3 /files/schedule.py

Run the autonomous agent

docker run --rm --entrypoint="" -v /your/local/path:/files \
  nvcr.io/nvidia/quantum/cuda-quantum:cu12-0.9.0 \
  python3 /files/agent.py

---

Agent Tools

The agent has three tools it selects between automatically based on your prompt:

Tool	Trigger Words	What It Does
optimize_schedule	optimize, schedule, generate, create	Runs full QAOA optimization
check_conflicts	conflict, check, valid, correct	Validates current schedule
show_schedule	show, display, timetable, current	Returns formatted schedule

All interactions are automatically logged to agent_log.txt with timestamps.

---

Key Concepts

QAOA (Quantum Approximate Optimization Algorithm): A variational hybrid algorithm that alternates between quantum problem layers and mixer layers, with a classical optimizer tuning the circuit parameters to minimize the Hamiltonian energy — which corresponds to finding the lowest-conflict schedule.

Hamiltonian Encoding: Each teacher conflict becomes a term 0.5 * Z(node_a) * Z(node_b) in the cost Hamiltonian. Minimizing this energy is equivalent to maximizing the number of satisfied constraints.

Multi-Start Optimization: The agent tries multiple random seeds and scans all measurement outcomes — not just the most frequent — to find conflict-free solutions reliably.

---

Results

The agent consistently finds a valid zero-conflict schedule within the first optimization seed, producing a result in under 30 seconds on CPU simulation.

---

Author

Joshua Ritz — github.com/21jritz

Built on NVIDIA NGC | CUDA-Q cu12-0.9.0 | LangChain 0.1.20 '@ $code | Out-File -FilePath "$env:USERPROFILE\Desktop\README.md" -Encoding utf8

Wait for the prompt, then verify:

```powershell
Get-Item "$env:USERPROFILE\Desktop\README.md" | Select-Object Name, Length