qbridge-agent 0.2.0

Local, compiler-backed CUDA-Q optimization agent

QBridge-Agent

Install and run

pip install "qbridge[quantum]" qbridge-agent
qbridge-agent my_problem.py --workspace ./qbridge-output

my_problem.py must be a supported QBridge Python DSL optimization model, not arbitrary Python. Add --no-solve to emit CUDA-Q without running it.

QBridge-Agent translates a constrained binary optimization request into the QBridge Python DSL, then delegates verified compilation and execution to the locally installed QBridge CUDA-Q compiler. It is deliberately not a general coding agent and has no cloud compile/solve dependency.

Layout

QBridge-Agent/
├── agent/
│   ├── planner/              # intent-to-DSL prompt policy
│   ├── tools/                # independent benchmark verification
│   ├── compiler_interface/   # DSL extraction, local compiler and CUDA-Q execution
├── examples/
├── evaluations/
│   ├── benchmark_tasks.json  # frozen T1/T2 task set
│   ├── results/              # raw reproducible run artifacts
│   └── README.md
└── README.md

Evaluation results

Run this in the Ubuntu environment that has CUDA-Q installed:

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.

OPENROUTER_API_KEY is required only for this external-model comparison; the normal agent compile/solve path is local. The reproducible 20 July 2026 run on the six frozen T1/T2 tasks (three trials each, NVIDIA cusvsim_fp32) found:

• QBridge-Agent: 16 VERIFIED, 1 INCORRECT, 1 UNVERIFIED.
• Aider: 0 VERIFIED, 17 UNVERIFIED, 1 INVALID_METHOD.

These are strict verifier outcomes, not success-rate estimates. Raw artifacts for that run are retained under evaluations/results/20260720_t1_t2_gpu_fixed in a source checkout and excluded from package distributions.

From a source checkout:

pip install .
qbridge-agent my_problem.py --workspace ./qbridge-output

qbridge-agent invokes the local qbridge package to emit CUDA-Q, then uses the configured local CUDA-Q target. No problem DSL is sent to a QBridge cloud endpoint.

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.