qbridge-agent 0.3.0

Local, compiler-backed CUDA-Q optimization agent

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.

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

Install and run locally

Prerequisites

• Python 3.9+
• qbridge[quantum] with CUDA-Q and an NVIDIA GPU target
• For natural-language mode: an OPENROUTER_API_KEY

From PyPI

pip install "qbridge[quantum]" qbridge-agent

From a source checkout

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

DSL file mode (no API key)

Compile and solve a QBridge DSL file:

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

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

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)

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:

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

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):

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.

Scope

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