Metadata-Version: 2.4
Name: qbridge-agent
Version: 0.2.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.1.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

## Install and run

```bash
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

```text
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:

```bash
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:

```bash
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](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.
