Metadata-Version: 2.4
Name: qbridge-agent
Version: 0.3.0
Summary: Local, compiler-backed CUDA-Q optimization agent
License-Expression: BUSL-1.1
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: qbridge[quantum]>=0.3.0
Requires-Dist: httpx>=0.27
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: ruff>=0.6.0; extra == "dev"
Dynamic: license-file

# QBridge-Agent

Local, compiler-backed CUDA-Q optimization agent. QBridge-Agent translates
constrained binary optimization problems into QBridge DSL, compiles them with
the installed QBridge CUDA-Q compiler, and runs on your local NVIDIA CUDA-Q
target.

![QBridge-Agent CLI compiling a QBridge DSL file locally](docs/cli-screenshot.png)

*Example: `qbridge-agent examples/knapsack_n5.py --workspace ./qbridge-output`*

## Install and run locally

### Prerequisites

- Python 3.9+
- [`qbridge[quantum]`](https://pypi.org/project/qbridge/) with CUDA-Q and an NVIDIA GPU target
- For natural-language mode: an `OPENROUTER_API_KEY`

### From PyPI

```bash
pip install "qbridge[quantum]" qbridge-agent
```

### From a source checkout

```bash
cd QbridgeAgentV2
pip install -e ".[dev]"
```

### DSL file mode (no API key)

Compile and solve a QBridge DSL file:

```bash
qbridge-agent examples/knapsack_n5.py --workspace ./qbridge-output
```

Compile only (emit CUDA-Q kernel without running the GPU):

```bash
qbridge-agent examples/knapsack_n5.py --workspace ./qbridge-output --no-solve
```

`examples/knapsack_n5.py` must be a supported QBridge Python DSL optimization
model (`import qbridge as qb`, declared variables, objective, constraints), not
arbitrary Python.

### Natural-language mode (uses OpenRouter)

```bash
export OPENROUTER_API_KEY=sk-or-...
qbridge-agent --prompt "Knapsack with 5 items, values [6,5,8,9,6], weights [2,3,4,5,3], capacity 8" \
  --workspace ./qbridge-output
```

Optional model override:

```bash
qbridge-agent --prompt "MaxCut on a 4-node cycle with edge weights 1,2,3,4" \
  --model openai/gpt-4o-mini \
  --workspace ./qbridge-output
```

## Layout

```text
QBridge-Agent/
├── agent/
│   ├── cli.py                # public CLI (DSL or --prompt)
│   ├── cudaq_entry.py        # programmatic NL agent entry
│   ├── planner/              # intent-to-DSL prompt policy
│   ├── tools/                # independent benchmark verification
│   └── compiler_interface/   # DSL extraction, local compiler and CUDA-Q execution
├── docs/
│   └── cli-screenshot.png    # terminal screenshot
├── examples/
├── evaluations/
│   ├── benchmark_tasks.json  # frozen T1/T2 task set
│   ├── results/              # raw reproducible run artifacts
│   └── README.md
└── README.md
```

## Evaluation results

Frozen six-task T1/T2 CUDA-Q benchmark (three trials per system, NVIDIA
`cusvsim_fp32`, `openai/gpt-4o-mini` via OpenRouter):

| Metric | QBridge-Agent | Aider |
|---|---:|---:|
| **VERIFIED** (of 18 trials) | **16** | **0** |
| Mean total tokens | 1,241 | 3,331 |
| Mean wall time | 3.8 s | 12.6 s |
| **Relative cost** | 1× | **2.68× tokens**, **~3.36× wall time** |

QBridge-Agent reached **16/18 verified** independent constraint/objective
checks; Aider reached **0/18**. On the same task set, Aider used **2.68×**
more tokens and **~3.36×** more wall-clock time per trial.

Run benchmarks in WSL Ubuntu with the CUDA-Q virtualenv (not Windows
`python`):

```bash
wsl -d Ubuntu -- bash -c "cd /mnt/c/Users/Dilip/Documents/ProjectQ/QbridgeAgentV2 && \
export PYTHONPATH=/mnt/c/Users/Dilip/Documents/ProjectQ/QbridgeAgentV2 && \
export OPENROUTER_API_KEY=\$OPENROUTER_API_KEY && \
/home/dilip/qbridge-env/bin/python3 evaluations/run_benchmark.py \
  --trials 3 --results evaluations/results/my_run"
```

The runner forces `cudaq.set_target("nvidia")`, performs a CUDA-Q sample GPU
probe before work begins, stores the actual target description for each V2
result, and checks both systems with the same classical feasibility/objective
verifier. It never converts an execution error into a successful result.

Token usage is captured for both systems: QBridge-Agent reads OpenRouter API
`usage` fields; Aider writes structured rows to `AIDER_USAGE_LOG` inside each
trial directory. Per-trial `result.json` files include `usage`, `usage_totals`,
and `timings` (`llm_s` / `aider_llm_s`, `driver_s` / `compile_solve_s`,
`wall_s`).

Raw artifacts for the 20 July 2026 runs are under
`evaluations/results/20260720_t1_t2_gpu_fixed` (verification) and
`evaluations/results/20260720_token_tracking_fixed` (token/timing capture).

`OPENROUTER_API_KEY` is required only for this external-model comparison; the
normal DSL compile/solve path is local. See `evaluations/README.md` for full
methodology and tables.

For maintainer release steps, see [RELEASE.md](RELEASE.md).

## Scope

Supported: small constrained binary optimization problems expressible in the
current QBridge DSL. Unsupported quantum algorithms and arbitrary Python are
errors, not guessed translations.
