qpi-client 0.0.3__py3-none-any.whl

qpi_client/__init__.py

@@ -0,0 +1,38 @@
+"""QPI Client SDK for Python.
+
+A client library for interacting with the QPI quantum computing platform.
+Provides both a low-level HTTP client and Qiskit-compatible backend/job classes.
+
+Usage::
+
+    from qpi_client import QPIClient
+
+    # Low-level client
+    client = QPIClient("http://localhost:8090", api_token="my-token")
+    job_id = client.submit_job([{"circuit": "OPENQASM 3.0; ..."}])
+
+    # Qiskit integration (preferred)
+    backend = client.get_backend(name="mock")
+    job = backend.run(circuit=my_circuit, shots=1024)
+    result = job.result()
+
+    # Or submit raw QASM
+    job = backend.run(qasm="OPENQASM 3.0; ...", params=[[0.5]])
+    result = job.result()
+
+    # Retrieve a past job
+    past_job = client.job(job_id)
+    past_job = backend.job(job_id)
+"""
+
+import importlib.metadata
+
+try:
+    __version__ = importlib.metadata.version("qpi-client")
+except importlib.metadata.PackageNotFoundError:
+    __version__ = "0.0.3"
+
+from qpi_client.client import QPIClient
+from qpi_client.provider import QPIBackend, QPIJob
+
+__all__ = ["__version__", "QPIClient", "QPIBackend", "QPIJob"]

qpi_client/client.py

@@ -0,0 +1,496 @@
+"""Low-level HTTP client for the QPI orchestrator REST API.
+
+This module provides :class:`QPIClient`, a thin wrapper around ``requests.Session``
+that handles authentication and serialisation for every QPI API endpoint.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+import requests
+
+if TYPE_CHECKING:
+    from qpi_client.provider import QPIBackend, QPIJob
+
+
+class QPIClient:
+    """Low-level HTTP wrapper for the QPI orchestrator API.
+
+    Args:
+        base_url: Root URL of the QPI orchestrator (e.g. ``"http://localhost:8090"``).
+        api_token: Optional API token used for authentication via the
+            ``X-API-Token`` header. When *None*, no token header is sent
+            (useful for cookie/JWT-based auth in browser contexts).
+    """
+
+    def __init__(self, base_url: str, api_token: str | None = None) -> None:
+        self.base_url: str = base_url.rstrip("/")
+        self.api_token: str | None = api_token
+        self._session: requests.Session = requests.Session()
+        self._session.headers["Content-Type"] = "application/json"
+        if api_token:
+            self._session.headers["X-API-Token"] = api_token
+
+    # -- public API ----------------------------------------------------------
+
+    def submit_job(
+        self,
+        circuits: list[dict[str, Any]],
+        shots: int = 1024,
+        meas_level: int = 2,
+        meas_return: str = "single",
+        qpu_target: str = "",
+    ) -> str:
+        """Submit a quantum job to the orchestrator.
+
+        Args:
+            circuits: A list of circuit payload dicts.  Each dict **must**
+                contain a ``"circuit"`` key whose value is an OpenQASM 3
+                string.  Optional keys: ``"parameter_values"``, ``"shots"``.
+            shots: Default number of shots for every circuit.
+            meas_level: Measurement level (``2`` = classified bits).
+            meas_return: ``"single"`` or ``"avg"``.
+            qpu_target: Optional QPU routing hint.
+
+        Returns:
+            The server-assigned job ID as a string.
+
+        Raises:
+            requests.HTTPError: If the server returns a non-2xx status.
+        """
+        payload: dict[str, Any] = {
+            "circuits": circuits,
+            "shots": shots,
+            "meas_level": meas_level,
+            "meas_return": meas_return,
+        }
+        if qpu_target:
+            payload["qpu_target"] = qpu_target
+
+        resp = self._session.post(f"{self.base_url}/api/jobs", json=payload)
+        resp.raise_for_status()
+        data = resp.json()
+
+        # The orchestrator may return the ID at the top level or nested.
+        job_id: str = data.get("id") or data.get("job_id", "")
+        if not job_id:
+            raise ValueError(f"Server response did not contain a job ID: {data!r}")
+        return job_id
+
+    def get_job(self, job_id: str) -> dict[str, Any]:
+        """Retrieve full details for *job_id*.
+
+        Returns:
+            A dict with at least ``"id"``, ``"status"``, ``"payload"``,
+            ``"results"``, ``"created"``, and ``"updated"`` keys.
+
+        Raises:
+            requests.HTTPError: If the server returns a non-2xx status.
+        """
+        resp = self._session.get(f"{self.base_url}/api/jobs/{job_id}")
+        resp.raise_for_status()
+        return resp.json()
+
+    def list_jobs(self) -> list[dict[str, Any]]:
+        """List all jobs belonging to the authenticated user.
+
+        Returns:
+            A list of job-record dicts.
+
+        Raises:
+            requests.HTTPError: If the server returns a non-2xx status.
+        """
+        resp = self._session.get(f"{self.base_url}/api/jobs")
+        resp.raise_for_status()
+        data = resp.json()
+        # The response might be a bare list or wrapped in {"jobs": [...]}.
+        if isinstance(data, list):
+            return data
+        return data.get("jobs", [])
+
+    def cancel_job(self, job_id: str) -> dict[str, Any]:
+        """Request cancellation of *job_id*.
+
+        Returns:
+            The updated job-record dict.
+
+        Raises:
+            requests.HTTPError: If the server returns a non-2xx status.
+        """
+        resp = self._session.post(f"{self.base_url}/api/jobs/{job_id}/cancel")
+        resp.raise_for_status()
+        return resp.json()
+
+    # -- high-level helpers --------------------------------------------------
+
+    def get_backend(self, name: str = "qpi") -> "QPIBackend":
+        """Return a :class:`QPIBackend` handle for the named QPU.
+
+        Args:
+            name: Backend / QPU name (e.g. ``"mock"``, ``"qiskit_aer"``).
+
+        Returns:
+            A configured :class:`QPIBackend` instance bound to this client.
+        """
+        from qpi_client.provider import QPIBackend
+
+        return QPIBackend(self, name=name)
+
+    def job(self, job_id: str) -> "QPIJob":
+        """Retrieve an existing job by ID.
+
+        Args:
+            job_id: The server-assigned job ID.
+
+        Returns:
+            A :class:`QPIJob` handle (backend will be *None*).
+        """
+        from qpi_client.provider import QPIJob
+
+        return QPIJob(backend=None, job_id=job_id, client=self)
+
+    # -- QPU discovery -------------------------------------------------------
+
+    def list_qpus(self) -> list[dict[str, Any]]:
+        """List all online QPUs.
+
+        Returns:
+            A list of QPU record dicts.
+        """
+        resp = self._session.get(f"{self.base_url}/api/qpus")
+        resp.raise_for_status()
+        return resp.json()
+
+    def get_qpu(self, name: str) -> dict[str, Any]:
+        """Retrieve a single QPU by name.
+
+        Args:
+            name: The QPU's unique name.
+
+        Returns:
+            A QPU record dict.
+        """
+        resp = self._session.get(f"{self.base_url}/api/qpus/{name}")
+        resp.raise_for_status()
+        return resp.json()
+
+    # -- QPU Registry & Toggles (admin-only) ---------------------------------
+
+    def create_qpu(
+        self,
+        name: str,
+        executor_type: str | None = None,
+        num_qubits: int | None = None,
+        enabled: bool | None = None,
+    ) -> dict[str, Any]:
+        """Create a new QPU record (admin-only).
+
+        The server generates a random ``access_token`` and returns it in
+        plain text exactly once; only the hash is persisted.
+
+        Args:
+            name: QPU name.
+            executor_type: Type of executor.
+            num_qubits: Number of qubits on the device.
+            enabled: Whether the QPU should be enabled (default ``True``).
+
+        Returns:
+            A dict containing at least ``id``, ``name``, ``access_token``,
+            ``executor_type``, ``status``, and ``enabled``.
+        """
+        payload: dict[str, Any] = {"name": name}
+        if executor_type is not None:
+            payload["executor_type"] = executor_type
+        if num_qubits is not None:
+            payload["num_qubits"] = num_qubits
+        if enabled is not None:
+            payload["enabled"] = enabled
+
+        resp = self._session.post(f"{self.base_url}/api/op/qpus/create", json=payload)
+        resp.raise_for_status()
+        return resp.json()
+
+    def connect_qpu(
+        self,
+        name: str,
+        access_token: str,
+        executor_type: str | None = None,
+        device_config: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """Connect a QPU driver node.
+
+        Args:
+            name: QPU name.
+            access_token: The access token for the QPU.
+            executor_type: Type of executor.
+            device_config: Configuration dict for the device.
+
+        Returns:
+            The connection response dict with NNG port assignments.
+        """
+        payload: dict[str, Any] = {
+            "name": name,
+            "access_token": access_token,
+        }
+        if executor_type is not None:
+            payload["executor_type"] = executor_type
+        if device_config is not None:
+            payload["device_config"] = device_config
+
+        resp = self._session.post(f"{self.base_url}/api/op/qpus/connect", json=payload)
+        resp.raise_for_status()
+        return resp.json()
+
+    def toggle_qpu(self, qpu_id: str, enabled: bool) -> dict[str, Any]:
+        """Toggle QPU driver state (admin-only).
+
+        Args:
+            qpu_id: ID of the QPU.
+            enabled: Whether the QPU should be enabled.
+
+        Returns:
+            Response dict.
+        """
+        resp = self._session.post(
+            f"{self.base_url}/api/op/qpu/toggle",
+            json={"id": qpu_id, "enabled": enabled},
+        )
+        resp.raise_for_status()
+        return resp.json()
+
+    # -- Notifications -------------------------------------------------------
+
+    def list_notifications(self) -> list[dict[str, Any]]:
+        """List notifications visible to the authenticated user.
+
+        Returns:
+            A list of notification record dicts.
+        """
+        resp = self._session.get(
+            f"{self.base_url}/api/collections/notifications/records"
+        )
+        resp.raise_for_status()
+        data = resp.json()
+        if isinstance(data, list):
+            return data
+        return data.get("items", [])
+
+    def dismiss_notification(self, notification_id: str) -> dict[str, Any]:
+        """Dismiss a notification for the authenticated user.
+
+        Args:
+            notification_id: ID of the notification.
+
+        Returns:
+            Response dict.
+        """
+        resp = self._session.post(
+            f"{self.base_url}/api/notifications/{notification_id}/dismiss"
+        )
+        resp.raise_for_status()
+        return resp.json()
+
+    # -- Booking Slots (time_slots) ------------------------------------------
+
+    def list_time_slots(self) -> list[dict[str, Any]]:
+        """List all booking slots.
+
+        Returns:
+            A list of booking slot record dicts.
+        """
+        resp = self._session.get(f"{self.base_url}/api/collections/time_slots/records")
+        resp.raise_for_status()
+        data = resp.json()
+        return data.get("items", [])
+
+    def create_time_slot(
+        self,
+        start_time: str,
+        end_time: str,
+        booked_by: str | None = None,
+    ) -> dict[str, Any]:
+        """Create a new booking slot.
+
+        Args:
+            start_time: Start time RFC3339 string.
+            end_time: End time RFC3339 string.
+            booked_by: Optional ID of the user booking the slot.
+
+        Returns:
+            The created booking slot dict.
+        """
+        payload = {"start_time": start_time, "end_time": end_time}
+        if booked_by is not None:
+            payload["booked_by"] = booked_by
+        resp = self._session.post(
+            f"{self.base_url}/api/collections/time_slots/records", json=payload
+        )
+        resp.raise_for_status()
+        return resp.json()
+
+    def update_time_slot(
+        self,
+        slot_id: str,
+        start_time: str | None = None,
+        end_time: str | None = None,
+    ) -> dict[str, Any]:
+        """Update an existing booking slot.
+
+        Args:
+            slot_id: ID of the booking slot.
+            start_time: Optional start time RFC3339 string.
+            end_time: Optional end time RFC3339 string.
+
+        Returns:
+            The updated booking slot dict.
+        """
+        payload = {}
+        if start_time is not None:
+            payload["start_time"] = start_time
+        if end_time is not None:
+            payload["end_time"] = end_time
+        resp = self._session.patch(
+            f"{self.base_url}/api/collections/time_slots/records/{slot_id}",
+            json=payload,
+        )
+        resp.raise_for_status()
+        return resp.json()
+
+    def delete_time_slot(self, slot_id: str) -> None:
+        """Delete a booking slot.
+
+        Args:
+            slot_id: ID of the booking slot.
+        """
+        resp = self._session.delete(
+            f"{self.base_url}/api/collections/time_slots/records/{slot_id}"
+        )
+        resp.raise_for_status()
+
+    # -- QPU Time Requests ---------------------------------------------------
+
+    def list_time_requests(self) -> list[dict[str, Any]]:
+        """List QPU time requests.
+
+        Returns:
+            A list of QPU time request record dicts.
+        """
+        resp = self._session.get(
+            f"{self.base_url}/api/collections/qpu_time_requests/records"
+        )
+        resp.raise_for_status()
+        data = resp.json()
+        return data.get("items", [])
+
+    def create_time_request(
+        self, seconds: int, requested_reason: str | None = None
+    ) -> dict[str, Any]:
+        """Create a new QPU time request.
+
+        Args:
+            seconds: Requested duration in seconds.
+            requested_reason: Optional explanation.
+
+        Returns:
+            The created QPU time request record dict.
+        """
+        payload = {"seconds": seconds}
+        if requested_reason is not None:
+            payload["requested_reason"] = requested_reason
+        resp = self._session.post(
+            f"{self.base_url}/api/collections/qpu_time_requests/records", json=payload
+        )
+        resp.raise_for_status()
+        return resp.json()
+
+    def update_time_request(
+        self,
+        request_id: str,
+        status: str,
+        rejection_reason: str | None = None,
+    ) -> dict[str, Any]:
+        """Update/Handle a QPU time request (admin-only).
+
+        Args:
+            request_id: ID of the time request.
+            status: "approved" or "rejected".
+            rejection_reason: Optional explanation if rejected.
+
+        Returns:
+            The updated request record dict.
+        """
+        payload = {"status": status}
+        if rejection_reason is not None:
+            payload["rejection_reason"] = rejection_reason
+        resp = self._session.patch(
+            f"{self.base_url}/api/collections/qpu_time_requests/records/{request_id}",
+            json=payload,
+        )
+        resp.raise_for_status()
+        return resp.json()
+
+    # -- Admin User Management -----------------------------------------------
+
+    def list_users(self) -> list[dict[str, Any]]:
+        """List all registered users (admin-only).
+
+        Returns:
+            A list of user record dicts.
+        """
+        resp = self._session.get(f"{self.base_url}/api/collections/users/records")
+        resp.raise_for_status()
+        data = resp.json()
+        return data.get("items", [])
+
+    def allocate_qpu_time(self, user_id: str, seconds: int) -> dict[str, Any]:
+        """Allocate QPU time to a user (admin-only).
+
+        Args:
+            user_id: ID of the user.
+            seconds: Total allocated seconds.
+
+        Returns:
+            The updated user record dict.
+        """
+        resp = self._session.patch(
+            f"{self.base_url}/api/collections/users/records/{user_id}",
+            json={"qpu_seconds": seconds},
+        )
+        resp.raise_for_status()
+        return resp.json()
+
+    # -- Auth helpers --------------------------------------------------------
+
+    def auth_with_password(self, identity: str, password: str) -> dict[str, Any]:
+        """Authenticate as a regular user using email/password.
+
+        Args:
+            identity: Email or username.
+            password: User password.
+
+        Returns:
+            The auth response payload including token and record.
+        """
+        resp = self._session.post(
+            f"{self.base_url}/api/collections/users/auth-with-password",
+            json={"identity": identity, "password": password},
+        )
+        resp.raise_for_status()
+        data = resp.json()
+        token = data.get("token")
+        if token:
+            self._session.headers["Authorization"] = f"Bearer {token}"
+        return data
+
+    # -- lifecycle -----------------------------------------------------------
+
+    def close(self) -> None:
+        """Close the underlying HTTP session."""
+        self._session.close()
+
+    def __enter__(self) -> "QPIClient":
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()

qpi_client/provider.py

@@ -0,0 +1,366 @@
+"""Qiskit provider integration for the QPI platform.
+
+This module exposes :class:`QPIBackend` (a Qiskit ``BackendV2``) and
+:class:`QPIJob` (a Qiskit ``JobV1``) so that QPI can be used as a
+drop-in Qiskit execution target::
+
+    from qiskit.circuit import QuantumCircuit
+    from qpi_client import QPIClient, QPIBackend
+
+    client = QPIClient("http://localhost:8090", api_token="tok")
+    backend = QPIBackend(client, num_qubits=5)
+
+    qc = QuantumCircuit(2, 2)
+    qc.h(0)
+    qc.cx(0, 1)
+    qc.measure([0, 1], [0, 1])
+
+    job = backend.run(qc, shots=4096)
+    result = job.result(timeout=120)
+    print(result.get_counts())
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Any, Sequence
+
+from qiskit.circuit import QuantumCircuit
+from qiskit.providers import BackendV2, JobStatus, JobV1, Options
+from qiskit.qasm3 import dumps as qasm3_dumps
+from qiskit.result import Result
+from qiskit.result.models import ExperimentResult, ExperimentResultData
+from qiskit.transpiler import Target
+
+from qpi_client.client import QPIClient
+
+# ---------------------------------------------------------------------------
+# QPIJob
+# ---------------------------------------------------------------------------
+
+
+class QPIJob(JobV1):
+    """A Qiskit-compatible job handle backed by the QPI REST API.
+
+    Instances are created by :meth:`QPIBackend.run` or :meth:`QPIClient.job`;
+    you should not need to instantiate this class directly.
+    """
+
+    def __init__(
+        self,
+        backend: "QPIBackend" | None,
+        job_id: str,
+        client: QPIClient,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(backend, job_id, **kwargs)
+        self._client = client
+        self._result: Result | None = None
+
+    @property
+    def id(self) -> str:
+        """Server-assigned job ID."""
+        return self.job_id()
+
+    # -- JobV1 interface -----------------------------------------------------
+
+    def submit(self) -> None:
+        """No-op — the job was already submitted by the backend."""
+
+    def result(
+        self,
+        timeout: float | None = None,
+        wait: float = 5.0,
+    ) -> Result:
+        """Block until the job completes and return a :class:`qiskit.result.Result`.
+
+        Args:
+            timeout: Maximum seconds to wait. *None* means wait indefinitely.
+            wait: Polling interval in seconds.
+
+        Returns:
+            A Qiskit :class:`Result` object populated with counts and
+            (optionally) memory from the QPI server response.
+
+        Raises:
+            TimeoutError: If the job does not finish within *timeout* seconds.
+            RuntimeError: If the job fails or is cancelled on the server.
+        """
+        if self._result is not None:
+            return self._result
+
+        start = time.monotonic()
+        while True:
+            data = self._client.get_job(self.job_id())
+            status = data.get("status", "")
+            if status in ("completed", "failed", "cancelled"):
+                break
+            if timeout is not None and (time.monotonic() - start) > timeout:
+                raise TimeoutError(
+                    f"Job {self.job_id()} did not complete within {timeout}s"
+                )
+            time.sleep(wait)
+
+        if status == "failed":
+            error_msg = ""
+            results_data = data.get("results")
+            if isinstance(results_data, dict):
+                error_msg = results_data.get("error", "")
+            raise RuntimeError(f"Job {self.job_id()} failed: {error_msg}")
+
+        if status == "cancelled":
+            raise RuntimeError(f"Job {self.job_id()} was cancelled")
+
+        self._result = self._build_result(data)
+        return self._result
+
+    def status(self) -> JobStatus:
+        """Return the current server-side status of the job."""
+        data = self._client.get_job(self.job_id())
+        _STATUS_MAP: dict[str, JobStatus] = {
+            "pending": JobStatus.QUEUED,
+            "queued": JobStatus.QUEUED,
+            "running": JobStatus.RUNNING,
+            "completed": JobStatus.DONE,
+            "failed": JobStatus.ERROR,
+            "cancelled": JobStatus.CANCELLED,
+        }
+        return _STATUS_MAP.get(data.get("status", ""), JobStatus.ERROR)
+
+    def cancel(self) -> None:
+        """Request cancellation of this job on the server."""
+        self._client.cancel_job(self.job_id())
+
+    # -- internal helpers ----------------------------------------------------
+
+    def _build_result(self, data: dict[str, Any]) -> Result:
+        """Construct a :class:`qiskit.result.Result` from the API response.
+
+        The server ``results`` payload may be:
+        * A dict with a top-level ``"circuit_results"`` list (one entry per
+          submitted circuit).
+        * A single dict with ``"counts"``/``"hex_counts"``/``"memory"`` keys
+          when only one circuit was submitted.
+        * ``None`` (edge-case) — we still return a valid *Result* with no
+          experiment data.
+        """
+        results_payload: Any = data.get("results") or {}
+
+        # Normalise to a list of per-circuit result dicts.
+        if isinstance(results_payload, dict):
+            circuit_results: list[dict[str, Any]] = results_payload.get(
+                "circuit_results", []
+            )
+            if not circuit_results:
+                # Treat the whole dict as a single-circuit result.
+                circuit_results = [results_payload]
+        elif isinstance(results_payload, list):
+            circuit_results = results_payload
+        else:
+            circuit_results = []
+
+        experiment_results: list[ExperimentResult] = []
+        for idx, cr in enumerate(circuit_results):
+            counts = cr.get("counts") or cr.get("hex_counts") or {}
+            # Ensure keys are hex-string formatted ("0x…").
+            hex_counts: dict[str, int] = {}
+            for key, val in counts.items():
+                if isinstance(key, int):
+                    hex_counts[hex(key)] = int(val)
+                elif key.startswith("0x") or key.startswith("0X"):
+                    hex_counts[key] = int(val)
+                else:
+                    # Assume binary string — convert to hex.
+                    try:
+                        hex_counts[hex(int(key, 2))] = int(val)
+                    except ValueError:
+                        hex_counts[key] = int(val)
+
+            exp_data = ExperimentResultData(
+                counts=hex_counts,
+                memory=cr.get("memory"),
+            )
+
+            experiment_results.append(
+                ExperimentResult(
+                    shots=cr.get(
+                        "shots", sum(hex_counts.values()) if hex_counts else 0
+                    ),
+                    success=True,
+                    data=exp_data,
+                    header=cr.get("header"),
+                )
+            )
+
+        return Result(
+            backend_name=self.backend().name if self.backend() else "qpi",
+            backend_version="0.1.0",
+            qobj_id=None,
+            job_id=self.job_id(),
+            success=True,
+            results=experiment_results,
+        )
+
+
+# ---------------------------------------------------------------------------
+# QPIBackend
+# ---------------------------------------------------------------------------
+
+
+class QPIBackend(BackendV2):
+    """A Qiskit ``BackendV2`` that submits circuits to the QPI orchestrator.
+
+    Args:
+        client: An authenticated :class:`QPIClient` instance.
+        name: Human-readable backend name (default ``"qpi"``).
+        num_qubits: Number of qubits the backend advertises to the Qiskit
+            transpiler.  Defaults to a large value so circuits of any
+            reasonable size compile without resizing the target.
+        **kwargs: Forwarded to :class:`BackendV2.__init__`.
+    """
+
+    def __init__(
+        self,
+        client: QPIClient,
+        name: str = "qpi",
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(name=name, **kwargs)
+        self._client = client
+        self._num_qubits = self._resolve_num_qubits(name)
+        self._target = Target(num_qubits=self._num_qubits)
+        self._options = Options()
+        self._options.update_options(
+            shots=1024,
+            meas_level=2,
+            meas_return="single",
+        )
+
+    def _resolve_num_qubits(self, name: str) -> int:
+        """Query the orchestrator for QPU info and return its num_qubits.
+
+        Raises:
+            RuntimeError: If the QPU cannot be found or has no valid num_qubits.
+        """
+        qpu = self._client.get_qpu(name)
+        try:
+            return int(qpu["num_qubits"])
+        except (TypeError, KeyError) as exp:
+            raise RuntimeError(
+                f"QPU '{name}' has no valid num_qubits (got {qpu.get('num_qubits')!r})"
+            ) from exp
+
+    # -- BackendV2 required properties ---------------------------------------
+
+    @property
+    def target(self) -> Target:
+        """Return the transpiler :class:`Target` for this backend."""
+        return self._target
+
+    @property
+    def max_circuits(self) -> int | None:
+        """No server-side limit on the number of circuits per job."""
+        return None
+
+    @classmethod
+    def _default_options(cls) -> Options:
+        return Options(shots=1024, meas_level=2, meas_return="single")
+
+    # -- execution -----------------------------------------------------------
+
+    def run(
+        self,
+        circuit: QuantumCircuit | Sequence[QuantumCircuit] | None = None,
+        qasm: str | None = None,
+        shots: int = 1024,
+        meas_level: int = 2,
+        meas_return: str = "single",
+        parameter_values: list[list[float]] | list[dict[Any, float]] | None = None,
+        **kwargs: Any,
+    ) -> QPIJob:
+        """Submit a quantum job to QPI.
+
+        Exactly one of ``circuit`` or ``qasm`` must be provided.
+
+        Args:
+            circuit: A single :class:`QuantumCircuit` or a list thereof.
+            qasm: A raw OpenQASM string (alternative to ``circuit``).
+            shots: Number of shots.
+            meas_level: Measurement level (``2`` = classified bits).
+            meas_return: ``"single"`` or ``"avg"``.
+            parameter_values: Parameter bindings.  For circuits this may be a
+                list of dicts mapping :class:`Parameter` objects to floats.
+                For raw QASM this should be a list of lists
+                (``[[0.5, 1.0]]``).
+
+        Returns:
+            A :class:`QPIJob` handle that can be polled or awaited.
+
+        Raises:
+            ValueError: If neither or both of ``circuit`` and ``qasm`` are
+                supplied.
+        """
+        if circuit is None and qasm is None:
+            raise ValueError("Either 'circuit' or 'qasm' must be provided")
+        if circuit is not None and qasm is not None:
+            raise ValueError("Only one of 'circuit' or 'qasm' should be provided")
+
+        pv = parameter_values
+        circuit_payloads: list[dict[str, Any]] = []
+
+        if circuit is not None:
+            if isinstance(circuit, QuantumCircuit):
+                circuits = [circuit]
+            else:
+                circuits = list(circuit)
+
+            # Grow the transpiler target if the circuit is larger than expected
+            max_qubits = max(qc.num_qubits for qc in circuits)
+            if max_qubits > self._num_qubits:
+                self._num_qubits = max_qubits
+                self._target = Target(num_qubits=max_qubits)
+
+            for idx, qc in enumerate(circuits):
+                if pv and idx < len(pv):
+                    pval = pv[idx]
+                    if isinstance(pval, dict) and pval:
+                        bound_qc = qc.assign_parameters(pval)
+                        qasm_str = qasm3_dumps(bound_qc)
+                        ordered_values = [float(pval[p]) for p in qc.parameters]
+                        circuit_payloads.append(
+                            {
+                                "circuit": qasm_str,
+                                "parameter_values": [ordered_values],
+                            }
+                        )
+                        continue
+
+                qasm_str = qasm3_dumps(qc)
+                circuit_payloads.append({"circuit": qasm_str})
+        else:
+            payload: dict[str, Any] = {"circuit": qasm}
+            if pv:
+                # Normalise single list to list of lists
+                if isinstance(pv[0], (int, float)):
+                    pv = [pv]  # type: ignore[assignment]
+                payload["parameter_values"] = pv
+            circuit_payloads.append(payload)
+
+        job_id = self._client.submit_job(
+            circuits=circuit_payloads,
+            shots=shots,
+            meas_level=meas_level,
+            meas_return=meas_return,
+        )
+        return QPIJob(self, job_id, self._client)
+
+    def job(self, job_id: str) -> QPIJob:
+        """Retrieve an existing job by ID.
+
+        Args:
+            job_id: The server-assigned job ID.
+
+        Returns:
+            A :class:`QPIJob` bound to this backend.
+        """
+        return QPIJob(self, job_id, self._client)

qpi_client-0.0.3.dist-info/METADATA

@@ -0,0 +1,11 @@
+Metadata-Version: 2.4
+Name: qpi-client
+Version: 0.0.3
+Summary: Python client SDK for the QPI quantum computing platform
+License: MIT
+Project-URL: Homepage, https://github.com/sopherapps/qpi
+Project-URL: Repository, https://github.com/sopherapps/qpi
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.28.0
+Requires-Dist: qiskit>=1.0.0

qpi_client-0.0.3.dist-info/RECORD

@@ -0,0 +1,7 @@
+qpi_client/__init__.py,sha256=Lh6wOuB3Z-5qu5KbFZWHFKjdr20cJlHAlk0W2sbkqD4,1096
+qpi_client/client.py,sha256=Fb9u1e8kwLb-CCKq4vjKoIgMVOx0hLdOuzdwrPfTZTU,16004
+qpi_client/provider.py,sha256=NE3PmZNulX9H_reOvJM329mPZvcjbxXYdG_GrtiVCJo,13119
+qpi_client-0.0.3.dist-info/METADATA,sha256=_sk1BxN44Q5uWG7qA9yfand3IutX11kVIEbtRkLTZxc,374
+qpi_client-0.0.3.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+qpi_client-0.0.3.dist-info/top_level.txt,sha256=2pfYOF8Y6ubKXMZuxOuwa4IdL9SjQ970y3qW1zM5MwI,11
+qpi_client-0.0.3.dist-info/RECORD,,

qpi_client-0.0.3.dist-info/WHEEL

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

qpi_client-0.0.3.dist-info/top_level.txt

@@ -0,0 +1 @@
+qpi_client