qbraid-core 0.3.2__tar.gz → 0.3.4__tar.gz

{qbraid_core-0.3.2/qbraid_core.egg-info → qbraid_core-0.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: qbraid-core
-Version: 0.3.2
+Version: 0.3.4
 Summary: Python library with core abstractions for software development in the qBraid ecosystem.
 Author: qBraid Development Team
 Author-email: contact@qbraid.com

{qbraid_core-0.3.2 → qbraid_core-0.3.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "qbraid-core"
-version = "0.3.2"
+version = "0.3.4"
 authors = [{name = "qBraid Development Team"}, {email = "contact@qbraid.com"}]
 description = "Python library with core abstractions for software development in the qBraid ecosystem."
 readme = "README.md"

{qbraid_core-0.3.2 → qbraid_core-0.3.4}/qbraid_core/services/compute/__init__.py

@@ -34,6 +34,9 @@ from .exceptions import (
     ComputeServiceRequestError,
 )
 from .schemas import (
+    BMAInstance,
+    BMAProgress,
+    BMAStatus,
     BuildInfo,
     BuildStatus,
     ComputeProfile,
@@ -69,6 +72,7 @@ from .ssh import (
     get_sshd_proxy_url,
     list_pod_ssh_configs,
     list_registered_keys,
+    parse_lab_url,
     read_public_key,
     register_public_key,
     remove_pod_ssh_config,
@@ -96,6 +100,10 @@ __all__ = [
     "ServerStopResponse",
     "SessionToken",
     "SessionTokenResponse",
+    # BMA on-demand instances
+    "BMAInstance",
+    "BMAProgress",
+    "BMAStatus",
     # Enums
     "ProfileType",
     "BuildStatus",
@@ -132,4 +140,5 @@ __all__ = [
     "add_sshd_proxy_config",
     "get_sshd_proxy_url",
     "get_proxy_command",
+    "parse_lab_url",
 ]

{qbraid_core-0.3.2 → qbraid_core-0.3.4}/qbraid_core/services/compute/client.py

@@ -21,6 +21,8 @@ from .exceptions import (
     ComputeServiceRequestError,
 )
 from .schemas import (
+    BMAInstance,
+    BMAStatus,
     BuildStatusResponse,
     ComputeProfile,
     ComputeSession,
@@ -57,6 +59,8 @@ class ComputeClient(QbraidClientV1):
     def __init__(self, *args, **kwargs):
         """Initialize the ComputeClient."""
         super().__init__(*args, **kwargs)
+        # Cache of docker-vm (BMA) profile slugs, populated lazily.
+        self._bma_slugs: Optional[set[str]] = None
 
     def _handle_error(self, err: RequestsApiError, operation: str) -> NoReturn:
         """Handle API errors and raise appropriate exceptions."""
@@ -646,7 +650,25 @@ class ComputeClient(QbraidClientV1):
             >>> response = client.start_server("2vCPU_4GB")
             >>> print(response.status)
             'starting'
+
+        Note:
+            On-demand ``docker-vm`` (BMA) profiles are routed transparently to
+            the BMA provision endpoint; the returned ServerStartResponse carries
+            the new instanceId in its ``message``. Use list_bma_instances() or
+            get_bma_instance() to track the instance afterward.
         """
+        if self.is_bma_profile(profile_slug):
+            instance = self.provision_bma_instance(profile_slug)
+            return ServerStartResponse.model_validate(
+                {
+                    "message": f"Provisioning instance {instance.instance_id}",
+                    "clusterId": cluster_id or "bma",
+                    "profile": profile_slug,
+                    "status": instance.status.value,
+                    "instanceId": instance.instance_id,
+                }
+            )
+
         body = {"profileSlug": profile_slug}
         if cluster_id is not None:
             body["clusterId"] = cluster_id
@@ -811,6 +833,320 @@ class ComputeClient(QbraidClientV1):
             **ssh_config,
         }
 
+    # =========================================================================
+    # BMA Instances (on-demand PAYG compute)
+    #
+    # These back the docker-vm profiles. The lifecycle is fire-and-forget:
+    # every action returns immediately with a transient status, and callers
+    # poll get_bma_instance() (or use wait_for_bma_instance()) until terminal.
+    # =========================================================================
+
+    _BMA_BASE = "/compute/bma/instances"
+
+    def is_bma_profile(self, profile_slug: str) -> bool:
+        """Whether a profile slug provisions an on-demand BMA instance.
+
+        ``docker-vm`` profiles route through the BMA lifecycle; all other
+        profiles use the legacy K8s server path. Used internally to keep
+        ``start_server``/``stop_server``/SSH transparent to the caller.
+
+        Detection uses the profile listing (the per-slug detail endpoint is not
+        reliably available across deployments). The slug set is cached for the
+        lifetime of the client on success; on transient errors we leave the
+        cache empty so the next call retries instead of permanently treating
+        every BMA profile as legacy.
+
+        Args:
+            profile_slug: Profile slug to classify.
+
+        Returns:
+            True if the profile is a docker-vm BMA profile.
+        """
+        slugs = getattr(self, "_bma_slugs", None)
+        if slugs is None:
+            try:
+                slugs = {p.slug for p in self.list_profiles() if p.spawner_type == "docker-vm"}
+            except ComputeServiceRequestError:
+                # Don't poison the cache; return False (treat as legacy) for
+                # this call and retry detection on the next invocation.
+                return False
+            self._bma_slugs = slugs
+        return profile_slug in slugs
+
+    def provision_bma_instance(self, profile_slug: str) -> BMAInstance:
+        """Provision (launch) a new on-demand BMA instance.
+
+        Fire-and-forget: returns immediately with status ``provisioning``.
+        Poll get_bma_instance() until ``running`` (open ``url``) or ``error``.
+
+        Args:
+            profile_slug: A docker-vm profile slug with a catalogSelector.
+
+        Returns:
+            BMAInstance with the new instanceId and transient status.
+        """
+        try:
+            response = self.session.post(self._BMA_BASE, json={"profileSlug": profile_slug})
+            resp_json = response.json()
+            return BMAInstance.model_validate(resp_json.get("data", resp_json))
+        except RequestsApiError as err:
+            self._handle_error(err, f"provision BMA instance '{profile_slug}'")
+        return None  # pragma: no cover
+
+    def list_bma_instances(self) -> list[BMAInstance]:
+        """List the caller's non-terminated BMA instances.
+
+        Returns:
+            List of BMAInstance (running, stopping, stopped, provisioning, error).
+        """
+        try:
+            response = self.session.get(self._BMA_BASE)
+            resp_json = response.json()
+            data = resp_json.get("data", resp_json)
+            return [BMAInstance.model_validate(item) for item in (data or [])]
+        except RequestsApiError as err:
+            self._handle_error(err, "list BMA instances")
+        return None  # pragma: no cover
+
+    def get_bma_instance(self, instance_id: str) -> BMAInstance:
+        """Get a single BMA instance (poll target).
+
+        Args:
+            instance_id: The BMA instance ID.
+
+        Returns:
+            Full BMAInstance object (including lastError).
+        """
+        try:
+            response = self.session.get(f"{self._BMA_BASE}/{instance_id}")
+            resp_json = response.json()
+            return BMAInstance.model_validate(resp_json.get("data", resp_json))
+        except RequestsApiError as err:
+            self._handle_error(err, f"get BMA instance '{instance_id}'")
+        return None  # pragma: no cover
+
+    def stop_bma_instance(self, instance_id: str) -> BMAInstance:
+        """Stop (pause) a running BMA instance, preserving its disk.
+
+        Fire-and-forget: flips to ``stopping`` and returns. Poll until
+        ``stopped``. Only a ``running`` instance can be stopped (else BAD_STATE).
+
+        Args:
+            instance_id: The BMA instance ID.
+
+        Returns:
+            BMAInstance with transient ``stopping`` status.
+        """
+        try:
+            response = self.session.post(f"{self._BMA_BASE}/{instance_id}/stop")
+            resp_json = response.json()
+            return BMAInstance.model_validate(resp_json.get("data", resp_json))
+        except RequestsApiError as err:
+            self._handle_error(err, f"stop BMA instance '{instance_id}'")
+        return None  # pragma: no cover
+
+    def start_bma_instance(self, instance_id: str) -> BMAInstance:
+        """Resume a stopped BMA instance.
+
+        Fire-and-forget: returns ``provisioning`` with a stable ``url`` that is
+        not live until status reaches ``running`` — poll first. Only a
+        ``stopped`` instance can resume (else BAD_STATE).
+
+        Args:
+            instance_id: The BMA instance ID.
+
+        Returns:
+            BMAInstance with transient status.
+        """
+        try:
+            response = self.session.post(f"{self._BMA_BASE}/{instance_id}/start")
+            resp_json = response.json()
+            return BMAInstance.model_validate(resp_json.get("data", resp_json))
+        except RequestsApiError as err:
+            self._handle_error(err, f"resume BMA instance '{instance_id}'")
+        return None  # pragma: no cover
+
+    def terminate_bma_instance(self, instance_id: str) -> BMAInstance:
+        """Terminate (delete) a BMA instance and its disk. Destructive.
+
+        Fire-and-forget but terminal immediately: the record flips to
+        ``terminated`` at once. Terminating an already-terminated instance is a
+        no-op.
+
+        Args:
+            instance_id: The BMA instance ID.
+
+        Returns:
+            BMAInstance with ``terminated`` status.
+        """
+        try:
+            response = self.session.delete(f"{self._BMA_BASE}/{instance_id}")
+            resp_json = response.json()
+            return BMAInstance.model_validate(resp_json.get("data", resp_json))
+        except RequestsApiError as err:
+            self._handle_error(err, f"terminate BMA instance '{instance_id}'")
+        return None  # pragma: no cover
+
+    def update_bma_cutoff(
+        self,
+        instance_id: str,
+        auto_stop_idle_minutes: Optional[int] = None,
+        max_session_minutes: Optional[int] = None,
+    ) -> BMAInstance:
+        """Update the auto-cutoff policy for a BMA instance.
+
+        At least one field must be provided. Values are integer minutes; ``0``
+        disables that cutoff.
+
+        Args:
+            instance_id: The BMA instance ID.
+            auto_stop_idle_minutes: Stop after this much idle (max 7 days).
+            max_session_minutes: Hard wall-clock cap from runningAt (max 30 days).
+
+        Returns:
+            BMAInstance reflecting the updated policy.
+
+        Raises:
+            ValueError: If neither field is provided.
+        """
+        body: dict[str, int] = {}
+        if auto_stop_idle_minutes is not None:
+            body["autoStopIdleMinutes"] = auto_stop_idle_minutes
+        if max_session_minutes is not None:
+            body["maxSessionMinutes"] = max_session_minutes
+        if not body:
+            raise ValueError(
+                "Provide at least one of auto_stop_idle_minutes or max_session_minutes."
+            )
+
+        try:
+            response = self.session.patch(f"{self._BMA_BASE}/{instance_id}", json=body)
+            resp_json = response.json()
+            return BMAInstance.model_validate(resp_json.get("data", resp_json))
+        except RequestsApiError as err:
+            self._handle_error(err, f"update cutoff for BMA instance '{instance_id}'")
+        return None  # pragma: no cover
+
+    def wait_for_bma_instance(
+        self,
+        instance_id: str,
+        target_status: BMAStatus = BMAStatus.RUNNING,
+        poll_interval: float = 4.0,
+        timeout: Optional[float] = 600.0,
+    ) -> BMAInstance:
+        """Poll a BMA instance until it reaches a terminal status.
+
+        Resolves when the instance hits ``target_status`` (or any terminal
+        status, or ``error``). GPU provisioning can take several minutes, so the
+        default timeout is generous.
+
+        Args:
+            instance_id: The BMA instance ID.
+            target_status: Desired terminal status (default: running).
+            poll_interval: Seconds between polls (default: 4).
+            timeout: Maximum seconds to wait (default: 600). None waits forever.
+
+        Returns:
+            The BMAInstance once it reaches a terminal/target status.
+
+        Raises:
+            TimeoutError: If the instance doesn't settle within timeout.
+            ComputeServiceRequestError: If the instance enters ``error``.
+        """
+        import time
+
+        terminal = {
+            BMAStatus.RUNNING,
+            BMAStatus.STOPPED,
+            BMAStatus.TERMINATED,
+            BMAStatus.ERROR,
+        }
+        start_time = time.time()
+        while True:
+            instance = self.get_bma_instance(instance_id)
+            if instance.status == target_status:
+                return instance
+            if instance.status == BMAStatus.ERROR:
+                msg = instance.last_error or (
+                    instance.progress.message if instance.progress else "unknown error"
+                )
+                raise ComputeServiceRequestError(
+                    f"BMA instance '{instance_id}' entered error state: {msg}"
+                )
+            if instance.status in terminal:
+                # Reached a different terminal state than requested; return it.
+                return instance
+            if timeout is not None and (time.time() - start_time) > timeout:
+                raise TimeoutError(
+                    f"BMA instance '{instance_id}' did not reach "
+                    f"'{target_status.value}' within {timeout}s "
+                    f"(last status: {instance.status.value})."
+                )
+            time.sleep(poll_interval)
+
+    @staticmethod
+    def bma_ssh_alias(instance_id: str) -> str:
+        """Derive a stable SSH config alias for a BMA instance.
+
+        Uses the instance ID's trailing hash so multiple instances of the same
+        profile get distinct aliases, e.g. ``bma-gpu-h100-sxm-016df951`` →
+        ``qbraid-bma-016df951``.
+
+        Args:
+            instance_id: The BMA instance ID.
+
+        Returns:
+            SSH config alias string.
+        """
+        suffix = instance_id.rsplit("-", 1)[-1] if "-" in instance_id else instance_id
+        return f"qbraid-bma-{suffix}"
+
+    def configure_ssh_for_instance(self, instance_id: str) -> dict:
+        """Configure SSH access for a single running BMA instance.
+
+        Fetches the instance, extracts the hub domain / username / token from
+        its live URL, and writes an SSH config entry with a per-instance alias
+        (see bma_ssh_alias). Multiple instances can be configured independently,
+        each reachable via its own alias.
+
+        Args:
+            instance_id: The BMA instance ID (must be running).
+
+        Returns:
+            Dict with SSH configuration details (alias, identity_file, commands).
+
+        Raises:
+            ComputeServiceRequestError: If the instance isn't running, has no
+                live URL, or the URL can't be parsed for SSH parts.
+        """
+        from .ssh import parse_lab_url, setup_qbraid_ssh
+
+        instance = self.get_bma_instance(instance_id)
+        if instance.status != BMAStatus.RUNNING or not instance.url:
+            raise ComputeServiceRequestError(
+                f"Instance '{instance_id}' is not running (status: "
+                f"{instance.status.value}); SSH can only be configured for a "
+                "running instance."
+            )
+
+        parts = parse_lab_url(instance.url)
+        hub_domain = parts["hub_domain"]
+        username = parts["username"]
+        token = parts["token"]
+        if not (hub_domain and username and token):
+            raise ComputeServiceRequestError(
+                f"Could not extract SSH connection details from instance " f"'{instance_id}' URL."
+            )
+
+        ssh_config = setup_qbraid_ssh(
+            username=username,
+            token=token,
+            host_alias=self.bma_ssh_alias(instance_id),
+            ide=parts["ide"] or "lab",
+            hub_domain=hub_domain,
+        )
+        return {"instance_id": instance_id, **ssh_config}
+
     # =========================================================================
     # Compute Sessions
     # =========================================================================

{qbraid_core-0.3.2 → qbraid_core-0.3.4}/qbraid_core/services/compute/schemas.py

@@ -60,6 +60,11 @@ class ComputeProfile(BaseModel):
     ide: str = Field(default="lab")
     has_capacity: bool = Field(default=True, alias="hasCapacity")
 
+    # Spawner routing: "docker-vm" profiles are on-demand BMA instances;
+    # everything else uses the legacy K8s server path.
+    spawner_type: Optional[str] = Field(default=None, alias="spawnerType")
+    catalog_selector: Optional[dict[str, Any]] = Field(default=None, alias="catalogSelector")
+
     # Resource configuration
     cpu_guarantee: Optional[float] = Field(default=None, alias="cpuGuarantee")
     cpu_limit: Optional[float] = Field(default=None, alias="cpuLimit")
@@ -175,11 +180,18 @@ class ProfileDetails(BaseModel):
     ide: str = Field(default="jupyterlab")
     cluster_id: Optional[str] = Field(default=None, alias="clusterId")
     has_capacity: bool = Field(default=True, alias="hasCapacity")
+    spawner_type: Optional[str] = Field(default=None, alias="spawnerType")
+    catalog_selector: Optional[dict[str, Any]] = Field(default=None, alias="catalogSelector")
     resources: Optional[ProfileResources] = None
     pricing: Optional[ProfilePricing] = None
 
     model_config = ConfigDict(populate_by_name=True)
 
+    @property
+    def is_bma(self) -> bool:
+        """Whether this profile provisions an on-demand BMA instance."""
+        return self.spawner_type == "docker-vm"
+
 
 class SessionToken(BaseModel):
     """JupyterHub session token."""
@@ -255,6 +267,9 @@ class ServerStartResponse(BaseModel):
     cluster_id: str = Field(..., alias="clusterId")
     profile: str
     status: str
+    # Set when the profile routed to the BMA layer (docker-vm); the new
+    # instance ID for tracking/SSH. None for legacy K8s servers.
+    instance_id: Optional[str] = Field(default=None, alias="instanceId")
 
     model_config = ConfigDict(populate_by_name=True)
 
@@ -359,3 +374,57 @@ class ComputeUsage(BaseModel):
     disk_usage: Optional[dict[str, Any]] = Field(default=None, alias="diskUsage")
 
     model_config = ConfigDict(populate_by_name=True)
+
+
+# =========================================================================
+# BMA Instances (on-demand PAYG compute)
+# =========================================================================
+
+
+class BMAStatus(str, Enum):
+    """Lifecycle status of a BMA instance."""
+
+    PROVISIONING = "provisioning"
+    RUNNING = "running"
+    STOPPING = "stopping"
+    STOPPED = "stopped"
+    TERMINATED = "terminated"
+    ERROR = "error"
+
+
+class BMAProgress(BaseModel):
+    """Progress object emitted at each lifecycle stage to drive a spinner/bar."""
+
+    phase: Optional[str] = (
+        None  # e.g. queued|creating|booting|starting|ready|resuming|stopping|error
+    )
+    percent: Optional[int] = None
+    message: Optional[str] = None
+
+    model_config = ConfigDict(populate_by_name=True)
+
+
+class BMAInstance(BaseModel):
+    """An on-demand BMA instance (docker-vm profile).
+
+    Returned by the ``/compute/bma/instances`` routes. The BMA layer hides the
+    underlying cloud vendor; the profile + specs are the user-facing identity.
+    """
+
+    instance_id: str = Field(..., alias="instanceId")
+    status: BMAStatus
+    profile_slug: Optional[str] = Field(default=None, alias="profileSlug")
+    url: Optional[str] = None  # live only when status == "running"
+    last_error: Optional[str] = Field(default=None, alias="lastError")  # GET-one only
+    created_at: Optional[datetime] = Field(default=None, alias="createdAt")
+    running_at: Optional[datetime] = Field(default=None, alias="runningAt")
+    stopped_at: Optional[datetime] = Field(default=None, alias="stoppedAt")
+    progress: Optional[BMAProgress] = None
+    ready: bool = Field(default=False)  # true only when running AND lab answers
+    pending: Optional[str] = None  # "spawn" | "stop" | None
+    auto_stop_idle_minutes: Optional[int] = Field(default=None, alias="autoStopIdleMinutes")
+    max_session_minutes: Optional[int] = Field(default=None, alias="maxSessionMinutes")
+    running_credits_per_min: Optional[float] = Field(default=None, alias="runningCreditsPerMin")
+    stopped_credits_per_min: Optional[float] = Field(default=None, alias="stoppedCreditsPerMin")
+
+    model_config = ConfigDict(populate_by_name=True, extra="ignore")

{qbraid_core-0.3.2 → qbraid_core-0.3.4}/qbraid_core/services/compute/ssh.py

@@ -868,6 +868,38 @@ def read_public_key(key_path: Optional[Path] = None) -> str:
     return pub_path.read_text().strip()
 
 
+def parse_lab_url(url: str) -> dict[str, Optional[str]]:
+    """Extract SSH connection parts from a lab/instance URL.
+
+    Handles both legacy server URLs and BMA instance URLs of the form
+    ``https://<host>/user/<username>/[<session>/]<ide>?token=<token>`` where
+    ``<username>`` may itself contain a session segment (e.g.
+    ``507f1f-kanavs/s-0e146b01``).
+
+    Args:
+        url: The lab URL (e.g. from ServerStatus.url or BMAInstance.url).
+
+    Returns:
+        Dict with keys ``hub_domain``, ``username``, ``token``, ``ide`` (any may
+        be None if not present in the URL).
+    """
+    import re
+    from urllib.parse import parse_qs, urlparse
+
+    parsed = urlparse(url)
+    token = parse_qs(parsed.query).get("token", [None])[0]
+    hub_domain = parsed.hostname
+
+    username: Optional[str] = None
+    ide: Optional[str] = None
+    match = re.search(r"/user/(.+?)/(lab|ssh|tree|vscode)(?:/|\?|$)", parsed.path)
+    if match:
+        username = match.group(1)
+        ide = match.group(2)
+
+    return {"hub_domain": hub_domain, "username": username, "token": token, "ide": ide}
+
+
 def _get_ssh_key_api_url(hub_domain: str, username: str, ide: str = "lab") -> str:
     """Get the URL for the SSH key management API.
 

{qbraid_core-0.3.2 → qbraid_core-0.3.4}/qbraid_core/services/runtime/client.py

@@ -15,7 +15,7 @@ from qbraid_core.exceptions import RequestsApiError
 from qbraid_core.registry import register_client
 
 from .exceptions import QuantumRuntimeServiceRequestError
-from .schemas.device import PlatformDevice, RuntimeDevice, RuntimeProvider
+from .schemas.device import DeviceCalibration, PlatformDevice, RuntimeDevice, RuntimeProvider
 from .schemas.group import GroupJob
 from .schemas.job import (
     JobRequest,
@@ -34,16 +34,21 @@ logger = logging.getLogger(__name__)
 class QuantumRuntimeClient(QbraidClientV1):
     """Client for interacting with the qBraid Runtime API."""
 
-    def list_devices(self) -> list[RuntimeDevice]:
+    def list_devices(self, include_retired: bool = False) -> list[RuntimeDevice]:
         """Returns a list of all quantum devices.
 
+        Args:
+            include_retired: If True, include devices with RETIRED status.
+                Defaults to False since retired devices cannot accept jobs.
+
         Per-device validation: if a single device fails to validate (e.g. the
         API added a new field shape or a value that doesn't match the schema),
         we log a warning and skip that device rather than failing the entire
         call. This keeps the panel/CLI working when new machines are added.
         """
         try:
-            response = self.session.get("/devices")
+            params = {} if include_retired else {"retired": "false"}
+            response = self.session.get("/devices", params=params)
             resp_data: list[dict[str, Any]] = response.json()["data"]
         except RequestsApiError as err:
             raise QuantumRuntimeServiceRequestError(f"Failed to retrieve devices: {err}") from err
@@ -57,18 +62,23 @@ class QuantumRuntimeClient(QbraidClientV1):
                 logger.warning("Skipping device %s due to validation error: %s", qrn, err)
         return validated
 
-    def list_platform_devices(self) -> list[PlatformDevice]:
+    def list_platform_devices(self, include_retired: bool = False) -> list[PlatformDevice]:
         """Returns a list of all quantum devices with full platform metadata.
 
         Unlike list_devices() which returns RuntimeDevice (minimal schema),
         this returns PlatformDevice which includes providerId, visibility,
         verification status, and other platform-specific fields.
 
+        Args:
+            include_retired: If True, include devices with RETIRED status.
+                Defaults to False since retired devices cannot accept jobs.
+
         Per-device validation: if a single device fails to validate,
         we log a warning and skip that device rather than failing the entire call.
         """
         try:
-            response = self.session.get("/devices")
+            params = {} if include_retired else {"retired": "false"}
+            response = self.session.get("/devices", params=params)
             resp_data: list[dict[str, Any]] = response.json()["data"]
         except RequestsApiError as err:
             raise QuantumRuntimeServiceRequestError(f"Failed to retrieve devices: {err}") from err
@@ -303,6 +313,17 @@ class QuantumRuntimeClient(QbraidClientV1):
                 f"Failed to retrieve device '{device_qrn}': {err}"
             ) from err
 
+    def get_device_calibrations(self, device_qrn: str) -> Optional[DeviceCalibration]:
+        """Returns calibration data for a device, or None if unavailable."""
+        try:
+            response = self.session.get(f"/devices/{device_qrn}/calibrations")
+            resp_data = response.json().get("data")
+            if resp_data is None:
+                return None
+            return DeviceCalibration.model_validate(resp_data)
+        except RequestsApiError:
+            return None
+
     def create_job(self, request: JobRequest) -> RuntimeJob:
         """Submits a new quantum job."""
         try:
@@ -481,6 +502,61 @@ class QuantumRuntimeClient(QbraidClientV1):
                 f"Failed to cancel group '{group_qrn}': {err}"
             ) from err
 
+    def delete_group(self, group_qrn: str) -> None:
+        """Delete a group record.
+
+        Deletes the group's metadata; the underlying jobs are not affected (use
+        ``cancel_group`` first if you want to stop them). Idempotent — deleting
+        an already-deleted group is a 404 we ignore here.
+
+        Args:
+            group_qrn: The group job QRN.
+        """
+        try:
+            self.session.delete(f"/jobs/group/{group_qrn}")
+        except RequestsApiError as err:
+            # Idempotent: a 404 means the group is already gone. Prefer the
+            # underlying HTTP status from the wrapped RequestException over
+            # substring-matching the error message (which would false-positive
+            # on unrelated errors like "schema validator not found").
+            cause = getattr(err, "__cause__", None)
+            response = getattr(cause, "response", None)
+            if response is not None and response.status_code == 404:
+                return
+            raise QuantumRuntimeServiceRequestError(
+                f"Failed to delete group '{group_qrn}': {err}"
+            ) from err
+
+    def get_group_jobs(self, group_qrn: str) -> list[RuntimeJob]:
+        """List the jobs that belong to a group.
+
+        Returns RuntimeJob (minimal schema, matching ``list_jobs``) so the call
+        succeeds whether the API serves the lean or platform-denormalized form.
+
+        Args:
+            group_qrn: The group job QRN.
+
+        Returns:
+            List of RuntimeJob objects in the group (any status).
+        """
+        try:
+            response = self.session.get(f"/jobs/group/{group_qrn}/jobs")
+            # Tolerate `"data": null` (treat as empty) and skip individual jobs
+            # that fail validation rather than dropping the whole list — keeps
+            # callers working when one job has unexpected/forward-compat fields.
+            resp_data: list[dict[str, Any]] = response.json().get("data") or []
+            jobs: list[RuntimeJob] = []
+            for job in resp_data:
+                try:
+                    jobs.append(RuntimeJob.model_validate(job))
+                except Exception:  # pylint: disable=broad-exception-caught
+                    continue
+            return jobs
+        except RequestsApiError as err:
+            raise QuantumRuntimeServiceRequestError(
+                f"Failed to list jobs for group '{group_qrn}': {err}"
+            ) from err
+
     def list_groups(
         self,
         status: Optional[str] = None,

{qbraid_core-0.3.2 → qbraid_core-0.3.4}/qbraid_core/services/runtime/schemas/__init__.py

@@ -6,10 +6,13 @@ Pydantic schemas for the qBraid Runtime API.
 """
 
 from .device import (
+    DeviceCalibration,
     DevicePricing,
     DeviceVerification,
+    EdgeEntry,
     PlatformDevice,
     ProviderLogo,
+    QubitCalibration,
     RuntimeDevice,
     RuntimeProvider,
 )
@@ -32,10 +35,13 @@ from .result import BatchResult, Result
 __all__ = [
     "GroupJob",
     "GroupStatus",
+    "DeviceCalibration",
     "DevicePricing",
     "DeviceVerification",
+    "EdgeEntry",
     "PlatformDevice",
     "ProviderLogo",
+    "QubitCalibration",
     "RuntimeDevice",
     "RuntimeProvider",
     "DeviceStatus",

{qbraid_core-0.3.2 → qbraid_core-0.3.4}/qbraid_core/services/runtime/schemas/device.py

@@ -12,7 +12,7 @@ from decimal import Decimal
 from enum import Enum
 from typing import TYPE_CHECKING, Any, Literal, Optional, Union
 
-from pydantic import BaseModel, ConfigDict, field_serializer, field_validator
+from pydantic import BaseModel, ConfigDict, Field, field_serializer, field_validator
 
 from qbraid_core.decimal import Credits
 
@@ -118,6 +118,7 @@ class RuntimeDevice(BaseModel):
     pricing: Optional[DevicePricing] = None  # only applies to fixed pricing model
     directAccess: bool = True
     batchJobSupport: bool = False
+    topology: Optional[dict[str, Any]] = None
 
 
 class DeviceVerification(Enum):
@@ -182,3 +183,39 @@ class RuntimeProvider(BaseModel):
     devices: list[str] = []
     logo: Optional[ProviderLogo] = None
     qrn: Optional[str] = None
+
+
+class EdgeEntry(BaseModel):
+    """Single two-qubit gate calibration measurement."""
+
+    model_config = ConfigDict(extra="ignore")
+
+    source: int
+    target: int
+    value: float
+
+
+class QubitCalibration(BaseModel):
+    """Per-qubit calibration metrics."""
+
+    model_config = ConfigDict(extra="ignore", populate_by_name=True)
+
+    t1: Optional[float] = None
+    t2: Optional[float] = None
+    frequency: Optional[float] = None
+    readout_error: Optional[float] = Field(None, alias="readoutError")
+    gate_error: Optional[dict[str, float]] = Field(None, alias="gateError")
+
+
+class DeviceCalibration(BaseModel):
+    """Device calibration snapshot."""
+
+    model_config = ConfigDict(extra="ignore", populate_by_name=True)
+
+    physical_device_id: str = Field(alias="physicalDeviceId")
+    device_qrns: list[str] = Field(alias="deviceQRNs")
+    provider: str
+    last_calibrated: str = Field(alias="lastCalibrated")
+    fetched_at: str = Field(alias="fetchedAt")
+    qubits: dict[str, QubitCalibration]
+    edges: dict[str, dict[str, list[EdgeEntry]]]

{qbraid_core-0.3.2 → qbraid_core-0.3.4/qbraid_core.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: qbraid-core
-Version: 0.3.2
+Version: 0.3.4
 Summary: Python library with core abstractions for software development in the qBraid ecosystem.
 Author: qBraid Development Team
 Author-email: contact@qbraid.com