shotgate 0.1.0__py3-none-any.whl

shotgate/__init__.py

@@ -0,0 +1,24 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (C) 2026 coldqubit
+"""shotgate — container-native CI/CD quality gates for quantum circuits.
+
+shotgate validates the *probabilistic* output of quantum circuits using statistical
+oracles (total variation distance, Hellinger fidelity, chi-square goodness-of-fit)
+so that quantum programs can be tested in ordinary CI/CD pipelines, across
+simulators and real QPUs, defined entirely as code.
+"""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+from shotgate.config import Workflow, load_workflow
+from shotgate.validation import Assertion, AssertionResult
+
+__all__ = [
+    "Assertion",
+    "AssertionResult",
+    "Workflow",
+    "__version__",
+    "load_workflow",
+]

shotgate/__main__.py

@@ -0,0 +1,8 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (C) 2026 coldqubit
+"""Enable ``python -m shotgate``."""
+
+from shotgate.cli import main
+
+if __name__ == "__main__":
+    main()

shotgate/backends/__init__.py

@@ -0,0 +1,19 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (C) 2026 coldqubit
+"""Pluggable execution backends for quantum circuits."""
+
+from shotgate.backends.base import Backend, BackendResult, BackendUnavailableError
+from shotgate.backends.registry import (
+    available_backends,
+    get_backend,
+    register_backend,
+)
+
+__all__ = [
+    "Backend",
+    "BackendResult",
+    "BackendUnavailableError",
+    "available_backends",
+    "get_backend",
+    "register_backend",
+]

shotgate/backends/base.py

@@ -0,0 +1,53 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (C) 2026 coldqubit
+"""Backend abstraction.
+
+A backend executes a circuit and returns measurement counts. The interface is
+intentionally minimal so new providers (local simulators, IBM, AWS Braket, …) can
+be added without touching the runner or the validation core. Heavy SDKs are
+imported lazily inside concrete backends, never at module import time.
+"""
+
+from __future__ import annotations
+
+import abc
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class BackendResult:
+    """Result of executing a circuit on a backend."""
+
+    counts: dict[str, int]
+    shots: int
+    backend_name: str
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+class Backend(abc.ABC):
+    """Abstract execution target for a quantum circuit."""
+
+    #: Stable provider identifier used in workflow YAML (e.g. ``"local-aer"``).
+    provider: str = "abstract"
+
+    def __init__(
+        self,
+        name: str | None = None,
+        options: dict[str, Any] | None = None,
+    ) -> None:
+        self.name = name
+        self.options = options or {}
+
+    @abc.abstractmethod
+    def run(self, circuit: Any, shots: int, seed: int | None = None) -> BackendResult:
+        """Execute ``circuit`` for ``shots`` repetitions and return counts."""
+
+    @classmethod
+    def is_available(cls) -> bool:
+        """Whether this backend's optional dependencies are importable."""
+        return True
+
+
+class BackendUnavailableError(RuntimeError):
+    """Raised when a backend is selected but its dependencies are missing."""

shotgate/backends/ibm_runtime.py

@@ -0,0 +1,153 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (C) 2026 coldqubit
+"""IBM Quantum backend (real QPUs and cloud simulators) via Qiskit Runtime.
+
+Credentials are read, in order of precedence, from the backend ``options`` token,
+the ``SHOTGATE_IBM_TOKEN`` environment variable, or the ``QISKIT_IBM_TOKEN``
+environment variable. Nothing is ever written to disk by shotgate.
+
+This backend is optional; install it with ``pip install shotgate[ibm]`` or use the
+``ghcr.io/coldqubit/shotgate:<ver>-ibm`` image variant.
+
+Status: **implemented but not yet validated on real hardware.** See
+``docs/hardware-validation.md`` for the plan to exercise it on an IBM QPU.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import os
+from typing import Any
+
+from shotgate.backends.base import Backend, BackendResult, BackendUnavailableError
+
+
+def _field(data: Any, name: str) -> Any:
+    """Access a DataBin field by name, tolerating mapping- or attribute-style access."""
+    try:
+        return data[name]
+    except (TypeError, KeyError):
+        return getattr(data, name)
+
+
+def _register_names(data: Any) -> list[str]:
+    """Return the classical-register field names of a Qiskit V2 ``DataBin``.
+
+    Recent qiskit exposes them via ``keys()``; we fall back to attribute discovery
+    for older/edge shapes.
+    """
+    if hasattr(data, "keys"):
+        try:
+            return list(data.keys())
+        except Exception:
+            # Fall through to attribute discovery for older/edge DataBin shapes.
+            pass
+    return [n for n in dir(data) if not n.startswith("_")]
+
+
+def extract_counts(pub_result: Any, register: str | None = None) -> dict[str, int]:
+    """Robustly read measurement counts from a Qiskit Runtime SamplerV2 pub result.
+
+    A V2 result's ``.data`` is a ``DataBin`` whose fields are the circuit's classical
+    registers (e.g. ``c`` from ``creg c[2]``, or ``meas`` from ``measure_all``); each
+    field is a ``BitArray`` exposing ``get_counts()``.
+
+    - If ``register`` is given, that register is used (error if absent).
+    - If exactly one register carries counts, it is used.
+    - Zero or multiple ambiguous registers raise a clear error rather than guessing.
+    """
+    data = pub_result.data
+    names = _register_names(data)
+    counts_fields = [
+        n for n in names if hasattr(_field(data, n), "get_counts")
+    ]
+
+    if register is not None:
+        if register not in counts_fields:
+            raise RuntimeError(
+                f"requested classical register {register!r} not found in result; "
+                f"available registers with counts: {counts_fields or names}"
+            )
+        chosen = register
+    elif len(counts_fields) == 1:
+        chosen = counts_fields[0]
+    elif not counts_fields:
+        raise RuntimeError(
+            "no classical register with counts found in the Sampler result "
+            f"(fields seen: {names}); ensure the circuit contains measurements"
+        )
+    else:
+        raise RuntimeError(
+            f"multiple classical registers {counts_fields} found; disambiguate by "
+            "setting backend.options.register to one of them"
+        )
+
+    bit_array = _field(data, chosen)
+    return {str(k): int(v) for k, v in bit_array.get_counts().items()}
+
+
+class IBMRuntimeBackend(Backend):
+    provider = "ibm"
+
+    @classmethod
+    def is_available(cls) -> bool:
+        return (
+            importlib.util.find_spec("qiskit") is not None
+            and importlib.util.find_spec("qiskit_ibm_runtime") is not None
+        )
+
+    def _token(self) -> str:
+        token = (
+            self.options.get("token")
+            or os.environ.get("SHOTGATE_IBM_TOKEN")
+            or os.environ.get("QISKIT_IBM_TOKEN")
+        )
+        if not token:
+            raise BackendUnavailableError(
+                "IBM backend requires an API token via backend.options.token, "
+                "SHOTGATE_IBM_TOKEN, or QISKIT_IBM_TOKEN"
+            )
+        return token
+
+    def run(self, circuit: Any, shots: int, seed: int | None = None) -> BackendResult:
+        from qiskit.transpiler.preset_passmanagers import generate_preset_pass_manager
+        from qiskit_ibm_runtime import QiskitRuntimeService, SamplerV2
+
+        # "ibm_quantum_platform" is the current channel; the legacy "ibm_quantum"
+        # name was removed in qiskit-ibm-runtime. Override via options if needed.
+        channel = self.options.get("channel", "ibm_quantum_platform")
+        instance = self.options.get("instance")
+        service = QiskitRuntimeService(
+            channel=channel, token=self._token(), instance=instance
+        )
+
+        if self.name:
+            backend = service.backend(self.name)
+        else:
+            backend = service.least_busy(operational=True, simulator=False)
+
+        pass_manager = generate_preset_pass_manager(
+            optimization_level=int(self.options.get("optimization_level", 1)),
+            backend=backend,
+        )
+        isa_circuit = pass_manager.run(circuit)
+
+        sampler = SamplerV2(mode=backend)
+        job = sampler.run([isa_circuit], shots=shots)
+        pub_result = job.result()[0]
+
+        # Robustly read counts from the named classical register(s) of the result.
+        counts = extract_counts(pub_result, register=self.options.get("register"))
+
+        return BackendResult(
+            counts=counts,
+            shots=shots,
+            backend_name=backend.name,
+            metadata={
+                "provider": self.provider,
+                "job_id": job.job_id(),
+                "channel": channel,
+                # seed is honored only on cloud simulators; ignored on real QPUs.
+                "seed_requested": seed,
+            },
+        )

shotgate/backends/local_aer.py

@@ -0,0 +1,46 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (C) 2026 coldqubit
+"""Local Qiskit Aer simulator backend.
+
+This is the default, zero-cost, fully-offline execution target: it runs entirely
+inside the shotgate container with no cloud credentials. Ideal for fast CI gating on
+small circuits (the report's "5-8 qubits, zero local RAM" MVP target).
+"""
+
+from __future__ import annotations
+
+import importlib.util
+from typing import Any
+
+from shotgate.backends.base import Backend, BackendResult
+
+
+class LocalAerBackend(Backend):
+    provider = "local-aer"
+
+    @classmethod
+    def is_available(cls) -> bool:
+        return (
+            importlib.util.find_spec("qiskit") is not None
+            and importlib.util.find_spec("qiskit_aer") is not None
+        )
+
+    def run(self, circuit: Any, shots: int, seed: int | None = None) -> BackendResult:
+        from qiskit import transpile
+        from qiskit_aer import AerSimulator
+
+        simulator = AerSimulator(**self.options)
+        compiled = transpile(circuit, simulator)
+        result = simulator.run(compiled, shots=shots, seed_simulator=seed).result()
+        counts = {str(k): int(v) for k, v in result.get_counts().items()}
+
+        return BackendResult(
+            counts=counts,
+            shots=shots,
+            backend_name=self.name or "aer_simulator",
+            metadata={
+                "provider": self.provider,
+                "method": simulator.options.get("method", "automatic"),
+                "seed": seed,
+            },
+        )

shotgate/backends/registry.py

@@ -0,0 +1,89 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (C) 2026 coldqubit
+"""Backend registry with lazy, dependency-free dispatch.
+
+Concrete backends are referenced by import path and only imported when actually
+requested, so importing shotgate (and running the validation core) never requires a
+quantum SDK to be installed.
+"""
+
+from __future__ import annotations
+
+import importlib
+
+from shotgate.backends.base import Backend, BackendUnavailableError
+from shotgate.config import BackendSpec
+
+# provider name -> "module:ClassName"
+_REGISTRY: dict[str, str] = {
+    "local-aer": "shotgate.backends.local_aer:LocalAerBackend",
+    "ibm": "shotgate.backends.ibm_runtime:IBMRuntimeBackend",
+}
+
+# provider name -> pip extra that supplies its dependencies
+_PROVIDER_EXTRA: dict[str, str] = {
+    "local-aer": "aer",
+    "ibm": "ibm",
+}
+
+
+def extra_for_provider(provider: str) -> str:
+    """Return the pip extra (``shotgate[<extra>]``) that supplies a provider's deps."""
+    return _PROVIDER_EXTRA.get(provider, provider)
+
+
+def _load_class(provider: str) -> type[Backend]:
+    try:
+        target = _REGISTRY[provider]
+    except KeyError:
+        raise ValueError(
+            f"unknown backend provider {provider!r}; "
+            f"available: {', '.join(sorted(_REGISTRY))}"
+        ) from None
+    module_name, class_name = target.split(":")
+    module = importlib.import_module(module_name)
+    return getattr(module, class_name)
+
+
+def get_backend(spec: BackendSpec) -> Backend:
+    """Instantiate the backend described by ``spec``.
+
+    Raises :class:`BackendUnavailableError` if the backend's optional
+    dependencies are not installed.
+    """
+    backend_cls = _load_class(spec.provider)
+    if not backend_cls.is_available():
+        extra = extra_for_provider(spec.provider)
+        raise BackendUnavailableError(
+            f"backend {spec.provider!r} is selected but its dependencies are not "
+            f"installed. Install the matching extra to use shotgate from a pip "
+            f"install (CLI or pytest plugin): pip install 'shotgate[{extra}]'. "
+            f"The published image ghcr.io/coldqubit/shotgate bakes the aer backend "
+            f"in (use the :latest-ibm tag for ibm)."
+        )
+    return backend_cls(name=spec.name, options=spec.options)
+
+
+def available_backends() -> dict[str, bool]:
+    """Map each known provider to whether its dependencies are importable."""
+    status: dict[str, bool] = {}
+    for provider in _REGISTRY:
+        try:
+            status[provider] = _load_class(provider).is_available()
+        except Exception:
+            status[provider] = False
+    return status
+
+
+def register_backend(provider: str, target: str) -> None:
+    """Register a third-party backend as ``"module:ClassName"`` (plugin hook)."""
+    _REGISTRY[provider] = target
+
+
+__all__ = [
+    "BackendUnavailableError",
+    "available_backends",
+    "extra_for_provider",
+    "get_backend",
+    "register_backend",
+]

shotgate/circuits/__init__.py

@@ -0,0 +1,7 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (C) 2026 coldqubit
+"""Circuit loading utilities."""
+
+from shotgate.circuits.loader import load_circuit
+
+__all__ = ["load_circuit"]

shotgate/circuits/loader.py

@@ -0,0 +1,57 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (C) 2026 coldqubit
+"""Load quantum circuits from a :class:`~shotgate.config.CircuitSpec`.
+
+OpenQASM (2.0 or 3.0) is the interchange format: it is portable across SDKs and
+keeps workflows free of executable Python, which matters for a tool that runs
+untrusted circuits in CI. Qiskit is imported lazily so the validation core stays
+dependency-free.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from shotgate.config import CircuitSpec
+
+
+def load_circuit(spec: CircuitSpec, base_dir: Path) -> Any:
+    """Return a Qiskit ``QuantumCircuit`` for ``spec``.
+
+    If the loaded circuit has no classical bits, a full measurement is appended so
+    that the backend produces counts.
+    """
+    text = _read_source(spec, base_dir)
+    circuit = _parse_qasm(text, spec.format)
+
+    if circuit.num_clbits == 0:
+        circuit.measure_all()
+    return circuit
+
+
+def _read_source(spec: CircuitSpec, base_dir: Path) -> str:
+    if spec.inline is not None:
+        return spec.inline
+    assert spec.path is not None  # guaranteed by CircuitSpec validation
+    circuit_path = (base_dir / spec.path).expanduser()
+    if not circuit_path.is_file():
+        raise FileNotFoundError(f"circuit file not found: {circuit_path}")
+    return circuit_path.read_text(encoding="utf-8")
+
+
+def _parse_qasm(text: str, fmt: str) -> Any:
+    if fmt == "qasm2":
+        from qiskit import qasm2
+
+        return qasm2.loads(
+            text, custom_instructions=qasm2.LEGACY_CUSTOM_INSTRUCTIONS
+        )
+    if fmt == "qasm3":
+        from qiskit import qasm3
+
+        return qasm3.loads(text)
+    raise ValueError(f"unsupported circuit format: {fmt!r}")
+
+
+__all__ = ["load_circuit"]

shotgate/cli.py

@@ -0,0 +1,130 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (C) 2026 coldqubit
+"""Command-line interface for shotgate.
+
+Commands
+--------
+- ``shotgate run WORKFLOW``      execute a workflow and gate CI on the result.
+- ``shotgate validate WORKFLOW`` schema-validate a workflow without executing it.
+- ``shotgate backends``          list backends and whether their deps are installed.
+
+Exit codes: ``0`` if all assertions pass, ``1`` if any fail, ``2`` for usage or
+load errors. This makes ``shotgate run`` a drop-in CI quality gate.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+
+from shotgate import __version__
+
+
+@click.group(context_settings={"help_option_names": ["-h", "--help"]})
+@click.version_option(__version__, prog_name="shotgate")
+def main() -> None:
+    """Container-native CI/CD quality gates for quantum circuits."""
+
+
+@main.command()
+@click.argument("workflow", type=click.Path(exists=True, dir_okay=False, path_type=Path))
+@click.option("--backend", "backend", default=None, help="Override the backend provider.")
+@click.option("--shots", type=int, default=None, help="Override shot count for all jobs.")
+@click.option(
+    "--junit",
+    type=click.Path(dir_okay=False, path_type=Path),
+    default=None,
+    help="Write a JUnit XML report to this path.",
+)
+@click.option(
+    "--json",
+    "json_path",
+    type=click.Path(dir_okay=False, path_type=Path),
+    default=None,
+    help="Write a JSON report to this path.",
+)
+@click.option(
+    "--markdown",
+    type=click.Path(dir_okay=False, path_type=Path),
+    default=None,
+    help="Write a Markdown summary to this path (e.g. $GITHUB_STEP_SUMMARY).",
+)
+@click.option("--quiet", is_flag=True, help="Suppress the console table.")
+def run(
+    workflow: Path,
+    backend: str | None,
+    shots: int | None,
+    junit: Path | None,
+    json_path: Path | None,
+    markdown: Path | None,
+    quiet: bool,
+) -> None:
+    """Execute WORKFLOW: run each job, validate output, and report."""
+    import typing
+
+    from shotgate.config import ProviderName, load_workflow
+    from shotgate.report import render_console, to_json, to_junit_xml, to_markdown
+    from shotgate.runner import Runner
+
+    valid_backends = typing.get_args(ProviderName)
+    if backend is not None and backend not in valid_backends:
+        raise click.ClickException(
+            f"unknown backend {backend!r}; valid backends: {', '.join(valid_backends)}"
+        )
+
+    try:
+        loaded = load_workflow(workflow)
+    except Exception as exc:
+        raise click.ClickException(f"failed to load workflow: {exc}") from exc
+
+    report = Runner(loaded, backend_override=backend, shots_override=shots).run()
+
+    if not quiet:
+        render_console(report)
+
+    if junit:
+        junit.write_text(to_junit_xml(report), encoding="utf-8")
+    if json_path:
+        json_path.write_text(to_json(report), encoding="utf-8")
+    if markdown:
+        markdown.write_text(to_markdown(report), encoding="utf-8")
+
+    raise SystemExit(0 if report.passed else 1)
+
+
+@main.command()
+@click.argument("workflow", type=click.Path(exists=True, dir_okay=False, path_type=Path))
+def validate(workflow: Path) -> None:
+    """Schema-validate WORKFLOW without executing any circuit."""
+    from shotgate.config import load_workflow
+
+    try:
+        loaded = load_workflow(workflow)
+    except Exception as exc:
+        raise click.ClickException(str(exc)) from exc
+
+    wf = loaded.workflow
+    click.secho(f"✓ valid workflow: {wf.metadata.name}", fg="green")
+    for job in wf.jobs:
+        spec = wf.effective_backend(job)
+        click.echo(
+            f"  - job {job.name}: {len(job.assertions)} assertion(s), "
+            f"backend={spec.provider}, shots={spec.shots}"
+        )
+
+
+@main.command()
+def backends() -> None:
+    """List available backends and whether their dependencies are installed."""
+    from shotgate.backends.registry import available_backends
+
+    for provider, ready in available_backends().items():
+        mark = click.style("ready", fg="green") if ready else click.style(
+            "missing deps", fg="yellow"
+        )
+        click.echo(f"  {provider:<12} {mark}")
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()