qbridge-agent 0.2.0__py3-none-any.whl

agent/__init__.py

@@ -0,0 +1,6 @@
+"""Lean CUDA-Q constrained-optimization agent."""
+
+from agent.models import Model, ModelResponse, OpenAICompatModel
+
+__all__ = ["Model", "ModelResponse", "OpenAICompatModel"]
+__version__ = "0.1.0"

agent/cli.py

@@ -0,0 +1,29 @@
+"""Public local CLI for the open-source QBridge Agent."""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from agent.compiler_interface.local_cudaq import compile_dsl_locally, solve_dsl_on_nvidia
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(prog="qbridge-agent")
+    parser.add_argument("dsl", type=Path, help="QBridge DSL source file")
+    parser.add_argument("--workspace", type=Path, default=Path.cwd())
+    parser.add_argument("--no-solve", action="store_true")
+    args = parser.parse_args()
+    source = args.dsl.read_text(encoding="utf-8")
+    paths, _ = compile_dsl_locally(source, args.workspace)
+    print(f"CUDA-Q written: {paths['cudaq']}")
+    if not args.no_solve:
+        result = solve_dsl_on_nvidia(source)
+        print(f"Backend: {result['backend']}")
+        print(f"Assignment: {result['assignment']}")
+        print(f"Objective: {result['objective_value']}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

agent/compiler_interface/__init__.py

@@ -0,0 +1,9 @@
+"""Lean CUDA-Q agent: NL -> QBridge DSL -> local compile/solve -> artifacts.
+
+No Aider, no chat UI, no git — only the deterministic product path from v1's
+``qbridge.quantum`` package (~0.8k LOC here).
+"""
+
+from agent.compiler_interface.pipeline import PipelineReport, QuantumPipeline, run_quantum_pipeline
+
+__all__ = ["PipelineReport", "QuantumPipeline", "run_quantum_pipeline"]

agent/compiler_interface/dsl_extract.py

@@ -0,0 +1,87 @@
+"""Client-safe DSL helpers (no compiler imports)."""
+
+from __future__ import annotations
+
+import re
+
+_FENCE_RE = re.compile(r"```(?:python)?\s*\n?(.*?)```", re.DOTALL | re.IGNORECASE)
+_THINK_RE = re.compile(
+    r"<think>.*?</think>|<thinking>.*?</thinking>|◁think▷.*?◁/think▷",
+    re.DOTALL | re.IGNORECASE,
+)
+_IMPORT_QB_RE = re.compile(
+    r"(?:^|\n)(import\s+qbridge\s+as\s+qb\b.*?)(?:\n```|\Z)",
+    re.DOTALL | re.IGNORECASE,
+)
+
+
+def strip_reasoning_text(raw: str) -> str:
+    """Remove common reasoning / think wrappers from model output."""
+    text = raw or ""
+    text = _THINK_RE.sub("", text)
+    # Drop leading "THINKING" / "ANSWER" section headers some UIs inject
+    text = re.sub(r"(?im)^\s*(thinking|reasoning)\s*$", "", text)
+    return text.strip()
+
+
+def extract_python_source(raw: str) -> str:
+    """Strip markdown fences / reasoning and return executable Python source."""
+    text = strip_reasoning_text(raw)
+    if not text:
+        return ""
+
+    # Prefer fenced python blocks that look like QBridge DSL
+    fences = list(_FENCE_RE.finditer(text))
+    if fences:
+        best = ""
+        for m in fences:
+            body = m.group(1).strip()
+            if "OptimizationProblem" in body or "import qbridge" in body:
+                return body
+            if len(body) > len(best):
+                best = body
+        if best:
+            return best
+
+    if text.startswith("```"):
+        lines = text.splitlines()
+        if lines and lines[0].startswith("```"):
+            lines = lines[1:]
+        if lines and lines[-1].strip() == "```":
+            lines = lines[:-1]
+        return "\n".join(lines).strip()
+
+    # Unfenced: grab from `import qbridge` onward when present
+    m = _IMPORT_QB_RE.search("\n" + text)
+    if m:
+        return m.group(1).strip()
+
+    return text
+
+
+def looks_like_qbridge_dsl(source: str) -> bool:
+    code = (source or "").strip()
+    if not code:
+        return False
+    return (
+        "import qbridge" in code
+        and "OptimizationProblem" in code
+        and ("problem" in code)
+        and (".minimize(" in code or ".maximize(" in code or "minimize(" in code or "maximize(" in code)
+    )
+
+
+def extract_and_validate_dsl(raw: str) -> tuple[str, str | None]:
+    """
+    Extract DSL and return (source, error).
+    error is set when the extract is empty or clearly not QBridge DSL.
+    """
+    source = extract_python_source(raw)
+    if not source.strip():
+        return "", "LLM returned empty content after stripping reasoning/fences."
+    if not looks_like_qbridge_dsl(source):
+        return source, (
+            "Extracted text is not valid QBridge DSL "
+            "(need import qbridge, OptimizationProblem, problem, minimize/maximize)."
+        )
+    return source, None

agent/compiler_interface/dsl_lint.py

@@ -0,0 +1,76 @@
+"""DSL lint — static checks before exec."""
+
+from __future__ import annotations
+
+import ast
+import re
+from typing import Any
+
+from agent.compiler_interface.dsl_extract import extract_python_source
+
+_FORBIDDEN_IMPORTS = {"cudaq", "subprocess", "os", "sys", "shutil"}
+_MAX_CONSTRAINTS = 64
+_MAX_ESTIMATED_VARS = 128
+
+
+def lint_dsl(source: str) -> dict[str, Any]:
+    """Return DSLValidationReport dict."""
+    code = extract_python_source(source)
+    issues: list[dict[str, str]] = []
+
+    if "problem" not in code:
+        issues.append({"code": "DSL_SYNTAX", "message": "Script must define variable `problem`."})
+    if "OptimizationProblem" not in code:
+        issues.append({"code": "DSL_SYNTAX", "message": "Must use OptimizationProblem."})
+    if re.search(r"\b(minimize|maximize)\s*\(", code) is None and ".minimize(" not in code and ".maximize(" not in code:
+        issues.append({"code": "MISSING_OBJECTIVE", "message": "Problem must set an objective."})
+
+    try:
+        tree = ast.parse(code)
+    except SyntaxError as exc:
+        issues.append({"code": "DSL_SYNTAX", "message": f"Syntax error: {exc}"})
+        return _report(issues)
+
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            for alias in node.names:
+                root = alias.name.split(".")[0]
+                if root in _FORBIDDEN_IMPORTS:
+                    issues.append({"code": "DSL_POLICY", "message": f"Forbidden import: {alias.name}"})
+        if isinstance(node, ast.ImportFrom) and node.module:
+            root = node.module.split(".")[0]
+            if root in _FORBIDDEN_IMPORTS:
+                issues.append({"code": "DSL_POLICY", "message": f"Forbidden import from: {node.module}"})
+
+    n_constraints = len(re.findall(r"add_constraint\s*\(", code))
+    if n_constraints > _MAX_CONSTRAINTS:
+        issues.append({"code": "DSL_POLICY", "message": f"Too many constraints ({n_constraints})."})
+
+    n_vars = len(re.findall(r"\b(Binary|Integer|Continuous)\s*\(", code))
+    if n_vars > _MAX_ESTIMATED_VARS:
+        issues.append({"code": "DSL_POLICY", "message": f"Too many variables ({n_vars})."})
+
+    if re.search(r"generate_cudaq|import\s+cudaq", code):
+        issues.append({"code": "DSL_POLICY", "message": "DSL must not generate CUDA-Q directly."})
+
+    # Modulo on symbolic ops is not supported by the compiler frontend
+    if re.search(r"%\s*\d|\d\s*%|%\s*[a-zA-Z_]", code):
+        issues.append(
+            {
+                "code": "DSL_POLICY",
+                "message": (
+                    "Do not use % modulo on variables. Prefer Binary + cardinality/cover "
+                    "constraints. Integer aux (s == 2*k) is a last resort — it adds qubits."
+                ),
+            }
+        )
+
+    return _report(issues)
+
+
+def _report(issues: list[dict[str, str]]) -> dict[str, Any]:
+    return {
+        "ok": len(issues) == 0,
+        "issues": issues,
+        "summary": "ok" if not issues else "; ".join(i["message"] for i in issues[:3]),
+    }

agent/compiler_interface/dsl_prompts.py

@@ -0,0 +1,99 @@
+"""System prompt and few-shot examples for the AI DSL translator."""
+
+SYSTEM_PROMPT = """You are a deterministic code translator. Your sole job is to convert optimization problem descriptions into Qbridge Python DSL scripts.
+
+RULES (strict):
+1. Output ONLY valid Python code inside one ```python fence. No explanations, no chain-of-thought, no commentary.
+2. Always start with: import qbridge as qb
+3. Always define: problem = qb.OptimizationProblem()
+4. Set objective with problem.minimize(...) or problem.maximize(...)
+5. Add constraints with problem.add_constraint(...)
+6. Use these variable factories:
+   - qb.Binary("name") for 0/1 decisions
+   - qb.Integer("name", lb=..., ub=...) for bounded integers
+   - qb.Continuous("name", lb=..., ub=..., precision_bits=...) for reals
+7. Optional: SOLVE_KWARGS = {"p": 4, "alpha": 10.0, "tight_encoding": True, "n_seeds": 3}
+8. Never import anything except qbridge.
+9. Never use print(), input(), file I/O, or network calls.
+10. Prefer Binary encodings for parity/cardinality when possible; keep qubit count low.
+11. Never use the Python % modulo operator on variables (unsupported). For evenness of a sum S,
+    prefer Binary variables and direct cardinality/cover constraints. Only as a last resort
+    introduce k = qb.Integer("k", lb=0, ub=...) with add_constraint(S == 2 * k) — Integer aux
+    variables add qubits.
+
+NAMING CONVENTIONS:
+- MaxCut: x0, x1, x2, ... (Binary)
+- Knapsack: q0, q1, ... (Integer quantities)
+- Graph Coloring: x_{vertex}_{color} (Binary), colors_used (Integer)
+
+OUTPUT FORMAT:
+Return exactly one ```python code block containing the complete script with a top-level `problem` variable.
+"""
+
+FEW_SHOT_EXAMPLES = [
+    {
+        "user": "MaxCut on a 4-node cycle graph. Maximize the number of cut edges.",
+        "assistant": '''```python
+import qbridge as qb
+
+x = [qb.Binary(f"x{i}") for i in range(4)]
+problem = qb.OptimizationProblem()
+cut_edges = []
+for i in range(4):
+    j = (i + 1) % 4
+    cut_edges.append(x[i] * (1 - x[j]) + (1 - x[i]) * x[j])
+problem.maximize(sum(cut_edges))
+
+SOLVE_KWARGS = {"p": 4, "alpha": 10.0, "tight_encoding": True, "n_seeds": 3}
+```''',
+    },
+    {
+        "user": "3-item knapsack: maximize value subject to weight capacity 30. Items have values [40, 35, 25] and weights [10, 15, 20]. Max quantity 5 per item.",
+        "assistant": '''```python
+import qbridge as qb
+
+values = [40, 35, 25]
+weights = [10, 15, 20]
+capacity = 30
+qty = [qb.Integer(f"q{i}", lb=0, ub=5) for i in range(3)]
+problem = qb.OptimizationProblem()
+problem.maximize(sum(values[i] * qty[i] for i in range(3)))
+problem.add_constraint(sum(weights[i] * qty[i] for i in range(3)) <= capacity)
+
+SOLVE_KWARGS = {"p": 4, "alpha": 10.0, "tight_encoding": True, "n_seeds": 3}
+```''',
+    },
+    {
+        "user": "Graph coloring: 3 vertices, 2 colors, edges (0,1) and (1,2). Minimize colors used.",
+        "assistant": '''```python
+import qbridge as qb
+
+n_vertices = 3
+k_colors = 2
+edges = [(0, 1), (1, 2)]
+x = {(v, c): qb.Binary(f"x_{v}_{c}") for v in range(n_vertices) for c in range(k_colors)}
+colors_used = qb.Integer("colors_used", lb=1, ub=k_colors)
+problem = qb.OptimizationProblem()
+problem.minimize(colors_used)
+for v in range(n_vertices):
+    problem.add_constraint(sum(x[v, c] for c in range(k_colors)) == 1)
+for u, v in edges:
+    for c in range(k_colors):
+        problem.add_constraint(x[u, c] + x[v, c] <= 1)
+problem.add_constraint(colors_used >= 2)
+problem.add_constraint(colors_used <= k_colors)
+
+SOLVE_KWARGS = {"p": 4, "alpha": 10.0, "tight_encoding": True, "n_seeds": 3}
+```''',
+    },
+]
+
+
+def build_translation_messages(user_description: str) -> list[dict[str, str]]:
+    """Build chat messages with system prompt, few-shots, and user request."""
+    messages: list[dict[str, str]] = [{"role": "system", "content": SYSTEM_PROMPT}]
+    for example in FEW_SHOT_EXAMPLES:
+        messages.append({"role": "user", "content": example["user"]})
+        messages.append({"role": "assistant", "content": example["assistant"]})
+    messages.append({"role": "user", "content": user_description})
+    return messages

agent/compiler_interface/local_cudaq.py

@@ -0,0 +1,61 @@
+"""Local, auditable QBridge DSL execution for CUDA-Q benchmarks.
+
+This is deliberately a narrow adapter: it parses the declared DSL with the
+compiler, forces CUDA-Q's NVIDIA target, and returns only the decoded result
+plus target evidence.  It never falls back to a classical simulator.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+
+def compile_dsl_locally(dsl_source: str, workspace_root: Path | str) -> tuple[dict[str, str], str]:
+    """Compile with the installed PyPI ``qbridge`` package, never a cloud API."""
+    from qbridge.dsl_build import compile_dsl_file
+
+    root = Path(workspace_root).resolve()
+    root.mkdir(parents=True, exist_ok=True)
+    dsl_path = root / "problem.py"
+    output = root / "compiled_output" / "kernel_execution.py"
+    dsl_path.write_text(dsl_source, encoding="utf-8")
+    generated = compile_dsl_file(dsl_path, output)
+    (output.parent / "compile_meta.json").write_text(
+        json.dumps({"backend": "local:qbridge", "artifact": str(generated)}, indent=2) + "\n",
+        encoding="utf-8",
+    )
+    return {"dsl": str(dsl_path), "cudaq": str(generated)}, generated.read_text(encoding="utf-8")
+
+def solve_dsl_on_nvidia(dsl_source: str, *, shots: int = 1024) -> dict[str, Any]:
+    """Compile and execute a declared QBridge optimization DSL on CUDA-Q GPU."""
+    try:
+        import cudaq
+        from qbridge.frontend.dsl_parser import parse_dsl_source
+        from qbridge.layer5_cudaq_codegen.backend import BackendConfig, BackendKind
+    except ImportError as exc:  # pragma: no cover - environment contract
+        raise RuntimeError("Local CUDA-Q compiler dependencies are unavailable") from exc
+
+    cudaq.set_target("nvidia")
+    target = str(cudaq.get_target())
+    if "nvidia" not in target.lower() and "cusv" not in target.lower():
+        raise RuntimeError(f"CUDA-Q did not select the NVIDIA target: {target}")
+
+    problem, solve_kwargs = parse_dsl_source(dsl_source)
+    # Benchmark settings are intentionally capped so generated DSL cannot turn
+    # an evaluation into an arbitrarily expensive experiment.
+    solve_kwargs.update({"shots": shots, "p": min(int(solve_kwargs.get("p", 2)), 2),
+                         "n_seeds": min(int(solve_kwargs.get("n_seeds", 1)), 2),
+                         "maxiter": min(int(solve_kwargs.get("maxiter", 30)), 50)})
+    result = problem.solve(
+        backend=BackendConfig(kind=BackendKind.CUDAQ_MGPU, target="nvidia", shots=shots),
+        **solve_kwargs,
+    )
+    return {
+        "assignment": dict(result.assignment),
+        "objective_value": result.objective_value,
+        "constraints_satisfied": result.constraints_satisfied,
+        "cudaq_target": target,
+        "backend": "cudaq:nvidia",
+    }

agent/compiler_interface/pipeline.py

@@ -0,0 +1,101 @@
+"""Local-only path: NL -> QBridge DSL -> installed compiler -> CUDA-Q GPU."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Callable
+
+from agent.compiler_interface.dsl_extract import extract_and_validate_dsl
+from agent.compiler_interface.dsl_lint import lint_dsl
+from agent.compiler_interface.dsl_prompts import SYSTEM_PROMPT, build_translation_messages
+from agent.compiler_interface.local_cudaq import compile_dsl_locally, solve_dsl_on_nvidia
+
+CompleteFn = Callable[[list[dict[str, str]]], str]
+
+
+@dataclass
+class PipelineReport:
+    ok: bool
+    summary: str
+    dsl_source: str = ""
+    local_files: dict[str, str] = field(default_factory=dict)
+    solution: dict[str, Any] = field(default_factory=dict)
+    error: str = ""
+    steps: list[str] = field(default_factory=list)
+
+
+class QuantumPipeline:
+    """Safe local compiler-backed agent; it has no cloud compile/solve step."""
+
+    def __init__(self, *, complete_fn: CompleteFn, workspace_root: Path | None = None,
+                 include_solve: bool = True, max_dsl_retries: int = 1, **_: Any) -> None:
+        self.complete_fn, self.workspace_root = complete_fn, Path(workspace_root or Path.cwd()).resolve()
+        self.include_solve, self.max_dsl_retries = include_solve, max_dsl_retries
+
+    def _extract(self, raw: str) -> str:
+        source, error = extract_and_validate_dsl(raw)
+        if error:
+            raise RuntimeError(error)
+        lint = lint_dsl(source)
+        if not lint["ok"]:
+            raise RuntimeError(lint["summary"])
+        return source
+
+    def _repair(self, source: str, error: str) -> str:
+        raw = self.complete_fn([
+            {"role": "system", "content": SYSTEM_PROMPT},
+            {"role": "user", "content": "Fix this DSL. Output only one Python fence.\n"
+             f"Compiler error: {error}\n```python\n{source}\n```"},
+        ])
+        return self._extract(raw)
+
+    def run(self, description: str) -> PipelineReport:
+        steps: list[str] = ["synthesize_dsl"]
+        try:
+            dsl = self._extract(self.complete_fn(build_translation_messages(description)))
+        except Exception as exc:  # noqa: BLE001
+            return PipelineReport(False, "", error=str(exc), steps=steps)
+
+        for attempt in range(self.max_dsl_retries + 1):
+            try:
+                steps.append("local_compile")
+                paths, _ = compile_dsl_locally(dsl, self.workspace_root)
+                solution: dict[str, Any] = {}
+                if self.include_solve:
+                    steps.append("local_cudaq_solve")
+                    result = solve_dsl_on_nvidia(dsl)
+                    solution = {
+                        "assignment": result["assignment"],
+                        "objective_value": result["objective_value"],
+                        "constraints_satisfied": result["constraints_satisfied"],
+                        "backend": result["backend"],
+                        "cudaq_target": result["cudaq_target"],
+                    }
+                    sol = self.workspace_root / "compiled_output" / "solution.json"
+                    sol.write_text(json.dumps(solution, indent=2) + "\n", encoding="utf-8")
+                    paths["solution"] = str(sol)
+                    if not solution["constraints_satisfied"]:
+                        raise RuntimeError("CUDA-Q solve returned an infeasible decoded assignment")
+                return PipelineReport(
+                    True,
+                    "\n".join(["Compiled locally with installed qbridge package", f"DSL: {paths['dsl']}",
+                               f"CUDA-Q: {paths['cudaq']}", f"Assignment: {solution.get('assignment')}"]),
+                    dsl, paths, solution, steps=steps,
+                )
+            except Exception as exc:  # noqa: BLE001
+                if attempt >= self.max_dsl_retries:
+                    return PipelineReport(False, "Compiled locally but execution failed.", dsl, error=str(exc), steps=steps)
+                steps.append("repair_dsl")
+                try:
+                    dsl = self._repair(dsl, str(exc))
+                except Exception as repair:  # noqa: BLE001
+                    return PipelineReport(False, "", dsl, error=str(repair), steps=steps)
+        raise AssertionError("unreachable")
+
+
+def run_quantum_pipeline(description: str, *, complete_fn: CompleteFn,
+                         workspace_root: Path | None = None, include_solve: bool = True) -> PipelineReport:
+    return QuantumPipeline(complete_fn=complete_fn, workspace_root=workspace_root,
+                           include_solve=include_solve).run(description)

agent/cudaq_entry.py

@@ -0,0 +1,86 @@
+"""Thin entry: NL problem -> DSL -> local compiler -> CUDA-Q artifacts."""
+
+from __future__ import annotations
+
+import json
+import time
+from pathlib import Path
+from typing import Any
+
+from agent.compiler_interface.pipeline import run_quantum_pipeline
+from agent.models import OpenAICompatModel
+
+
+def run_cudaq_case(
+    *,
+    prompt: str,
+    workspace: Path,
+    model: str,
+    api_key: str,
+    base_url: str = "https://openrouter.ai/api/v1",
+    seed: int | None = None,
+    enable_cot: bool = False,
+    max_tokens: int = 4096,
+) -> dict[str, Any]:
+    """Run one lean AgentV2 CUDA-Q case; write paper-suite artifact layout."""
+    workspace = Path(workspace)
+    workspace.mkdir(parents=True, exist_ok=True)
+    (workspace / "prompt.txt").write_text(prompt, encoding="utf-8")
+
+    extra: dict[str, Any] = {"usage": {"include": True}}
+    if seed is not None:
+        extra["seed"] = seed
+    if enable_cot:
+        extra["reasoning"] = {"effort": "high"}
+        extra["chat_template_kwargs"] = {"enable_thinking": True}
+    else:
+        extra["reasoning"] = {"effort": "none", "exclude": True}
+        extra["chat_template_kwargs"] = {"enable_thinking": False}
+
+    llm = OpenAICompatModel(
+        model=model,
+        api_key=api_key,
+        base_url=base_url,
+        temperature=0.0,
+        max_tokens=max_tokens,
+        timeout=600.0,
+        extra_body=extra,
+    )
+
+    def complete_fn(messages: list[dict[str, str]]) -> str:
+        return llm.generate_messages(messages).text
+
+    t0 = time.perf_counter()
+    report = run_quantum_pipeline(
+        prompt,
+        complete_fn=complete_fn,
+        workspace_root=workspace,
+        include_solve=True,
+    )
+    wall = time.perf_counter() - t0
+
+    usage_rows = list(llm.last_usage_log)
+    meta = {
+        "usage": usage_rows,
+        "ok": report.ok,
+        "error": report.error,
+        "summary": report.summary,
+        "steps": report.steps,
+        "solution": report.solution,
+        "timings": {"wall_s": wall},
+        "native_retry_policy": (
+            "max_dsl_retries=1; lean AgentV2 (no Aider); local CUDA-Q; "
+            + ("CoT on" if enable_cot else "CoT off")
+        ),
+    }
+    (workspace / "_usage.json").write_text(json.dumps(meta, indent=2), encoding="utf-8")
+    return {
+        "ok": report.ok,
+        "error": report.error,
+        "solution": report.solution,
+        "usage": usage_rows,
+        "wall_s": wall,
+        "dsl_source": report.dsl_source,
+        "steps": report.steps,
+        "summary": report.summary,
+    }

agent/models.py

@@ -0,0 +1,164 @@
+"""Model abstraction for prompt → text (+ usage)."""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass
+class ModelResponse:
+    text: str
+    prompt_tokens: int = 0
+    completion_tokens: int = 0
+    latency_ms: float = 0.0
+
+    @property
+    def total_tokens(self) -> int:
+        return self.prompt_tokens + self.completion_tokens
+
+
+class Model(ABC):
+    """Provider-agnostic text generation."""
+
+    @abstractmethod
+    def generate(self, prompt: str, *, system: str | None = None) -> ModelResponse:
+        """Return model text and usage metadata."""
+
+
+class MockModel(Model):
+    """Deterministic offline model. Keys are case ids or exact prompt prefixes.
+
+    Lookup order:
+    1. ``case_id`` kw via ``set_case`` / active case
+    2. Exact full prompt match in ``responses``
+    3. Prefix match
+    """
+
+    def __init__(self, responses: dict[str, str] | None = None) -> None:
+        self.responses = dict(responses or {})
+        self._active_case: str | None = None
+
+    def set_case(self, case_id: str | None) -> None:
+        self._active_case = case_id
+
+    def generate(self, prompt: str, *, system: str | None = None) -> ModelResponse:
+        t0 = time.perf_counter()
+        text = ""
+        if self._active_case and self._active_case in self.responses:
+            text = self.responses[self._active_case]
+        elif prompt in self.responses:
+            text = self.responses[prompt]
+        else:
+            for key, value in self.responses.items():
+                if prompt.startswith(key) or key in prompt:
+                    text = value
+                    break
+        if not text:
+            text = self.responses.get("__default__", "")
+        # Crude token estimate for offline runs
+        blob = (system or "") + prompt + text
+        tokens = max(1, len(blob.split()))
+        latency = (time.perf_counter() - t0) * 1000
+        return ModelResponse(
+            text=text,
+            prompt_tokens=max(1, tokens // 2),
+            completion_tokens=max(1, len(text.split()) or 1),
+            latency_ms=latency,
+        )
+
+
+class OpenAICompatModel(Model):
+    """OpenAI Chat Completions-compatible HTTP client (cloud or local)."""
+
+    def __init__(
+        self,
+        *,
+        model: str = "gpt-4o-mini",
+        api_key: str | None = None,
+        base_url: str = "https://api.openai.com/v1",
+        temperature: float = 0.0,
+        max_tokens: int = 1024,
+        timeout: float = 60.0,
+        extra_body: dict[str, Any] | None = None,
+    ) -> None:
+        self.model = model
+        self.api_key = api_key or os.environ.get("OPENAI_API_KEY", "")
+        self.base_url = base_url.rstrip("/")
+        self.temperature = temperature
+        self.max_tokens = max_tokens
+        self.timeout = timeout
+        self.extra_body = dict(extra_body or {})
+        self.last_usage_log: list[dict[str, Any]] = []
+
+    def generate(self, prompt: str, *, system: str | None = None) -> ModelResponse:
+        messages: list[dict[str, str]] = []
+        if system:
+            messages.append({"role": "system", "content": system})
+        messages.append({"role": "user", "content": prompt})
+        return self.generate_messages(messages)
+
+    def generate_messages(self, messages: list[dict[str, str]]) -> ModelResponse:
+        """Multi-turn chat (used by the lean CUDA-Q quantum pipeline)."""
+        import httpx
+
+        url = f"{self.base_url}/chat/completions"
+        headers = {"Authorization": f"Bearer {self.api_key}"} if self.api_key else {}
+        body: dict[str, Any] = {
+            "model": self.model,
+            "messages": messages,
+            "temperature": self.temperature,
+            "max_tokens": self.max_tokens,
+            **self.extra_body,
+        }
+        t0 = time.perf_counter()
+        with httpx.Client(timeout=self.timeout) as client:
+            resp = client.post(url, headers=headers, json=body)
+            resp.raise_for_status()
+            data = resp.json()
+        latency = (time.perf_counter() - t0) * 1000
+        text = data["choices"][0]["message"]["content"] or ""
+        usage = data.get("usage") or {}
+        rec = {
+            "prompt_tokens": int(usage.get("prompt_tokens") or 0),
+            "completion_tokens": int(usage.get("completion_tokens") or 0),
+            "total_tokens": int(usage.get("total_tokens") or 0),
+        }
+        self.last_usage_log.append(rec)
+        return ModelResponse(
+            text=text,
+            prompt_tokens=rec["prompt_tokens"],
+            completion_tokens=rec["completion_tokens"],
+            latency_ms=latency,
+        )
+
+
+def extract_json_object(text: str) -> dict[str, Any]:
+    """Pull the first JSON object from model output (fences allowed)."""
+    raw = text.strip()
+    if raw.startswith("```"):
+        lines = raw.splitlines()
+        if lines and lines[0].startswith("```"):
+            lines = lines[1:]
+        if lines and lines[-1].strip() == "```":
+            lines = lines[:-1]
+        raw = "\n".join(lines).strip()
+        if raw.lower().startswith("json"):
+            raw = raw[4:].lstrip()
+    try:
+        obj = json.loads(raw)
+        if isinstance(obj, dict):
+            return obj
+    except json.JSONDecodeError:
+        pass
+    start = raw.find("{")
+    end = raw.rfind("}")
+    if start >= 0 and end > start:
+        obj = json.loads(raw[start : end + 1])
+        if isinstance(obj, dict):
+            return obj
+    raise ValueError(f"No JSON object in model output: {text[:200]!r}")

agent/planner/__init__.py

@@ -0,0 +1,5 @@
+"""Intent-to-DSL planning surface (currently constrained optimization)."""
+
+from agent.compiler_interface.dsl_prompts import build_translation_messages
+
+__all__ = ["build_translation_messages"]

agent/tools/__init__.py

@@ -0,0 +1 @@
+"""Shared verification and execution utilities."""

agent/tools/cudaq_verification.py

@@ -0,0 +1,33 @@
+"""Shared, model-agnostic correctness checks for frozen CUDA-Q tasks."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def verify(assignment: dict[str, Any] | None, problem: dict[str, Any]) -> dict[str, Any]:
+    if not isinstance(assignment, dict):
+        return {"status": "UNVERIFIED", "ok": False, "notes": ["no assignment"]}
+    x = [int(assignment.get(f"x{i}", assignment.get(str(i), 0))) for i in range(problem["num_vars"])]
+    inst, bad = problem["instance"], []
+    objective = (
+        sum(v * x[i] for i, v in enumerate(inst["values"]))
+        if "values" in inst
+        else sum(w * (x[u] ^ x[v]) for u, v, w in inst["edges"])
+    )
+    if "capacity" in inst and sum(w * x[i] for i, w in enumerate(inst["weights"])) > inst["capacity"]:
+        bad.append("capacity")
+    if "cardinality" in inst and sum(x) != inst["cardinality"]:
+        bad.append("cardinality")
+    if "k" in inst and sum(x) != inst["k"]:
+        bad.append("k")
+    if any(x[a] and x[b] for a, b in inst.get("conflicts", [])):
+        bad.append("conflict")
+    if any(not any(x[i] for i in group) for group in inst.get("groups_at_least_one", [])):
+        bad.append("group_cover")
+    if "exactly_one" in inst and sum(x[i] for i in inst["exactly_one"]) != 1:
+        bad.append("exactly_one")
+    optimum = problem["classical_reference"]["optimal_objective"]
+    return {"status": "VERIFIED" if not bad else "INCORRECT", "ok": not bad,
+            "assignment": {f"x{i}": bit for i, bit in enumerate(x)}, "objective": objective,
+            "objective_gap": (optimum - objective) / optimum if not bad else None, "notes": bad}

qbridge_agent-0.2.0.dist-info/METADATA

@@ -0,0 +1,92 @@
+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.

qbridge_agent-0.2.0.dist-info/RECORD

@@ -0,0 +1,19 @@
+agent/__init__.py,sha256=GZWoQijFftkd2POUs1VN0UcJgIOavfvDzcB8548To20,197
+agent/cli.py,sha256=DifhhgXsaRx-bbH24xUMv6isvmbR18Bfg8YQUG4XApM,996
+agent/cudaq_entry.py,sha256=IddVUow4IhapgHoABfS7iAkJhDjEZsMXJK1oFeNkFUo,2535
+agent/models.py,sha256=x5zYAQ6oZvSP_Ahdhf525LAJAf52rFunv8HAw72rRGo,5598
+agent/compiler_interface/__init__.py,sha256=wXWXyc8IluIGL-dWY2q0L0IYxvJmEFCax2S_MYs-MJc,381
+agent/compiler_interface/dsl_extract.py,sha256=ACF7A_5R2AhDL1SzDp-apqwlDxghC6YkVMQrwb9Xnno,2764
+agent/compiler_interface/dsl_lint.py,sha256=BLmqZtRFompKlPHD1TWNz-UkL_SAfRYFa7fS02gIS_U,3003
+agent/compiler_interface/dsl_prompts.py,sha256=mpcAuFvKlEuO2gV3jgAgAdYF8ORUkjDSfO9TIOfwtvs,4102
+agent/compiler_interface/local_cudaq.py,sha256=aXGoLxKlpW2SX2aaTJpgesWtVZrJAwpIJEUnYs--aAE,2764
+agent/compiler_interface/pipeline.py,sha256=tZx1_GtTJ_PV8p7D4pOZxWEMDuSQX-tBTRzcNTqXd_I,4689
+agent/planner/__init__.py,sha256=l5-_mDigSGRkwZpssTbr1KpF6dMYw_qb2QslJvCx2yo,194
+agent/tools/__init__.py,sha256=1njzsHyLDWJ-C2mEt5apK22nvVmulZPTG657gjnwtEg,51
+agent/tools/cudaq_verification.py,sha256=P0xP_6YbN0_kAsYq7ALjtBcXveLRapGSkfbe1CGkfc4,1632
+qbridge_agent-0.2.0.dist-info/licenses/LICENSE,sha256=l7p_HHOXVNXZKCk96iH4gNPEt6N8eT-3zXDffsoc1pg,1971
+qbridge_agent-0.2.0.dist-info/METADATA,sha256=Y2G4VlPwj4YY3EZTpbdwr_jAocIXhnbtu7TOREvUpzg,3186
+qbridge_agent-0.2.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+qbridge_agent-0.2.0.dist-info/entry_points.txt,sha256=gH2SrEqlzKhVxMbVNAGYhdlFNbIP1e0aBWdIQzMIIuQ,49
+qbridge_agent-0.2.0.dist-info/top_level.txt,sha256=0gvCG7PHc22NA63j3bTGi2Zc37ym9t8Pf90ZLzf1kGA,6
+qbridge_agent-0.2.0.dist-info/RECORD,,

qbridge_agent-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

qbridge_agent-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+qbridge-agent = agent.cli:main

qbridge_agent-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,43 @@
+Business Source License 1.1
+
+License text copyright (c) 2017 MariaDB Corporation Ab, All Rights Reserved.
+"Business Source License" is a trademark of MariaDB Corporation Ab.
+
+Parameters
+
+Licensor: QBridge contributors
+Licensed Work: QBridge Agent, including all source files in this repository.
+Additional Use Grant: You may use, copy, modify, create derivative works of,
+and redistribute the Licensed Work for any purpose, provided that any
+redistribution before the Change Date is under this License and retains this
+notice.
+Change Date: 2030-07-20
+Change License: Apache License, Version 2.0
+
+Terms
+
+The Licensed Work is made available under the terms of this Business Source
+License. On the Change Date, or the fourth anniversary of the first public
+release of each later version of the Licensed Work, whichever is later, the
+Licensed Work will be made available under the Change License.
+
+The Licensor grants you the right to copy, modify, create derivative works of,
+redistribute, and make non-production use of the Licensed Work. The Additional
+Use Grant above specifies any additional permitted production use.
+
+The Licensed Work is provided on an "AS IS" basis. The Licensor disclaims all
+warranties, express or implied, including merchantability, fitness for a
+particular purpose, and non-infringement. In no event will the Licensor be
+liable for any damages arising from use of the Licensed Work.
+
+You must conspicuously display this License on each copy of the Licensed Work
+that you redistribute. Any use of the Licensed Work in violation of this
+License automatically terminates your rights under this License.
+
+This License does not grant any right to use the Licensor's trademarks, except
+as required for reasonable and customary use in describing the origin of the
+Licensed Work.
+
+On the Change Date, the Licensed Work is licensed under the Apache License,
+Version 2.0. A copy of that license is available at
+https://www.apache.org/licenses/LICENSE-2.0.

qbridge_agent-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+agent