qbraid-core 0.2.2__tar.gz → 0.2.3__tar.gz

{qbraid_core-0.2.2/qbraid_core.egg-info → qbraid_core-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: qbraid-core
-Version: 0.2.2
+Version: 0.2.3
 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.2.2 → qbraid_core-0.2.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "qbraid-core"
-version = "0.2.2"
+version = "0.2.3"
 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.2.2 → qbraid_core-0.2.3}/qbraid_core/services/runtime/client.py

@@ -15,6 +15,7 @@ from qbraid_core.registry import register_client
 
 from .exceptions import QuantumRuntimeServiceRequestError
 from .schemas.device import RuntimeDevice
+from .schemas.group import GroupJob
 from .schemas.job import JobRequest, Program, RuntimeJob
 from .schemas.result import Result
 
@@ -183,3 +184,124 @@ class QuantumRuntimeClient(QbraidClientV1):
             raise QuantumRuntimeServiceRequestError(
                 f"Failed to retrieve program for job '{job_qrn}': {err}"
             ) from err
+
+    def create_group(
+        self,
+        name: Optional[str] = None,
+        tags: Optional[dict[str, Any]] = None,
+        metadata: Optional[dict[str, Any]] = None,
+        max_ttl: Optional[int] = None,
+    ) -> GroupJob:
+        """Create a new group job session.
+
+        Args:
+            name: Optional human-readable name for the group.
+            tags: Optional tags for filtering/grouping.
+            metadata: Optional metadata dict.
+            max_ttl: Optional max time-to-live in seconds (1–86400).
+                The backend defaults to 3600 (1 hour) if not provided.
+
+        Returns:
+            GroupJob with status OPEN and a generated groupJobQrn.
+        """
+        body: dict[str, Any] = {}
+        if name is not None:
+            body["name"] = name
+        if tags is not None:
+            body["tags"] = tags
+        if metadata is not None:
+            body["metadata"] = metadata
+        if max_ttl is not None:
+            body["maxTTL"] = max_ttl
+
+        try:
+            response = self.session.post("/jobs/group", json=body)
+            resp_data: dict[str, Any] = response.json()["data"]
+            return GroupJob.model_validate(resp_data)
+        except RequestsApiError as err:
+            raise QuantumRuntimeServiceRequestError(f"Failed to create group: {err}") from err
+
+    def get_group(self, group_qrn: str) -> GroupJob:
+        """Retrieve group details by QRN.
+
+        Args:
+            group_qrn: The group job QRN.
+
+        Returns:
+            GroupJob with current status, counters, and job list.
+        """
+        try:
+            response = self.session.get(f"/jobs/group/{group_qrn}")
+            resp_data: dict[str, Any] = response.json()["data"]
+            return GroupJob.model_validate(resp_data)
+        except RequestsApiError as err:
+            raise QuantumRuntimeServiceRequestError(
+                f"Failed to retrieve group '{group_qrn}': {err}"
+            ) from err
+
+    def close_group(self, group_qrn: str) -> GroupJob:
+        """Close a group (no new jobs accepted, existing jobs continue).
+
+        Args:
+            group_qrn: The group job QRN.
+
+        Returns:
+            Updated GroupJob with status CLOSED.
+        """
+        try:
+            response = self.session.post(f"/jobs/group/{group_qrn}/close")
+            resp_data: dict[str, Any] = response.json()["data"]
+            return GroupJob.model_validate(resp_data)
+        except RequestsApiError as err:
+            raise QuantumRuntimeServiceRequestError(
+                f"Failed to close group '{group_qrn}': {err}"
+            ) from err
+
+    def cancel_group(self, group_qrn: str) -> GroupJob:
+        """Cancel a group and all its non-terminal jobs.
+
+        Args:
+            group_qrn: The group job QRN.
+
+        Returns:
+            Updated GroupJob with status CANCELLED.
+        """
+        try:
+            response = self.session.post(f"/jobs/group/{group_qrn}/cancel")
+            resp_data: dict[str, Any] = response.json()["data"]
+            return GroupJob.model_validate(resp_data)
+        except RequestsApiError as err:
+            raise QuantumRuntimeServiceRequestError(
+                f"Failed to cancel group '{group_qrn}': {err}"
+            ) from err
+
+    def list_groups(
+        self,
+        status: Optional[str] = None,
+        page: Optional[int] = None,
+        limit: Optional[int] = None,
+    ) -> list[GroupJob]:
+        """List group jobs for the current user.
+
+        Args:
+            status: Filter by group status (OPEN, CLOSED, COMPLETED, FAILED, CANCELLED).
+            page: Page number for pagination.
+            limit: Number of results per page.
+
+        Returns:
+            List of GroupJob objects.
+        """
+        params: dict[str, Any] = {}
+        if status is not None:
+            params["status"] = status
+        if page is not None:
+            params["page"] = page
+        if limit is not None:
+            params["limit"] = limit
+
+        try:
+            response = self.session.get("/jobs/group", params=params if params else None)
+            resp_data: list[dict[str, Any]] = response.json()["data"]
+            return [GroupJob.model_validate(group) for group in resp_data]
+        except RequestsApiError as err:
+            raise QuantumRuntimeServiceRequestError(f"Failed to list groups: {err}") from err

{qbraid_core-0.2.2 → qbraid_core-0.2.3}/qbraid_core/services/runtime/schemas/__init__.py

@@ -7,10 +7,13 @@ Pydantic schemas for the qBraid Runtime API.
 
 from .device import DevicePricing, RuntimeDevice
 from .enums import DeviceStatus, ExperimentType, JobStatus
+from .group import GroupJob, GroupStatus
 from .job import JobBase, JobRequest, Program, RuntimeJob, TimeStamps
 from .result import Result
 
 __all__ = [
+    "GroupJob",
+    "GroupStatus",
     "DevicePricing",
     "RuntimeDevice",
     "DeviceStatus",

qbraid_core-0.2.3/qbraid_core/services/runtime/schemas/group.py

@@ -0,0 +1,91 @@
+# Copyright (c) 2025, qBraid Development Team
+# All rights reserved.
+
+"""
+Pydantic schemas for group job API requests and responses.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any, Optional
+
+from pydantic import BaseModel, Field, field_serializer
+
+from qbraid_core.decimal import Credits
+
+from .job import TimeStamps
+
+
+class GroupStatus(str, Enum):
+    """Status of a group job session.
+
+    Attributes:
+        OPEN: Group is accepting new job submissions.
+        CLOSED: Group is closed for new submissions; jobs still executing.
+        COMPLETED: All jobs reached COMPLETED state.
+        FAILED: All jobs in terminal state, and at least 1 failed.
+        CANCELLED: Group was explicitly cancelled by the user.
+    """
+
+    OPEN = "OPEN"
+    CLOSED = "CLOSED"
+    COMPLETED = "COMPLETED"
+    FAILED = "FAILED"
+    CANCELLED = "CANCELLED"
+
+    @classmethod
+    def terminal_states(cls) -> set[GroupStatus]:
+        """Returns the set of terminal group statuses."""
+        return {cls.COMPLETED, cls.FAILED, cls.CANCELLED}
+
+
+class GroupJob(BaseModel):
+    """Schema for group job response model.
+
+    Returned by the runtime API when creating, retrieving, or listing groups.
+    The SDK's GroupJobSession wraps this model.
+    """
+
+    groupJobQrn: str = Field(..., description="Group job resource name")
+    name: Optional[str] = Field(None, description="User-assigned group name")
+    status: GroupStatus = Field(..., description="Group status")
+    organizationUserId: str = Field(..., description="Organization user ID")
+
+    # Job tracking
+    jobCount: int = Field(0, ge=0, description="Total number of jobs in the group")
+    completedCount: int = Field(0, ge=0, description="Number of completed jobs")
+    failedCount: int = Field(0, ge=0, description="Number of failed jobs")
+    cancelledCount: int = Field(0, ge=0, description="Number of cancelled jobs")
+
+    # Cost aggregation
+    totalEstimatedCost: Optional[Credits] = Field(
+        None, ge=0, description="Sum of estimated costs for all jobs"
+    )
+    totalCost: Optional[Credits] = Field(
+        None, ge=0, description="Sum of actual costs for completed jobs"
+    )
+
+    # Timestamps
+    timeStamps: Optional[TimeStamps] = Field(None, description="Group timestamps")
+
+    # TTL
+    maxTTL: Optional[int] = Field(
+        None, ge=1, le=86400, description="Max time-to-live in seconds (1s – 86400s / 24h)"
+    )
+
+    # User metadata
+    tags: dict[str, Any] = Field(default_factory=dict, description="User-defined tags")
+    metadata: dict[str, Any] = Field(default_factory=dict, description="Additional metadata")
+
+    @field_serializer("totalEstimatedCost", "totalCost")
+    def serialize_credits(self, value: Optional[Credits]) -> Optional[float]:
+        """Serialize Credits to float for JSON response."""
+        if value is None:
+            return None
+        return float(value)
+
+    @field_serializer("status")
+    def serialize_status(self, value: GroupStatus) -> str:
+        """Serialize GroupStatus enum to its string value."""
+        return value.value

{qbraid_core-0.2.2 → qbraid_core-0.2.3}/qbraid_core/services/runtime/schemas/job.py

@@ -11,7 +11,13 @@ import sys
 from datetime import datetime
 from typing import Any, Literal, Optional, Union
 
-from pydantic import BaseModel, Field, field_serializer, field_validator, model_validator
+from pydantic import (
+    BaseModel,
+    Field,
+    field_serializer,
+    field_validator,
+    model_validator,
+)
 
 from qbraid_core.decimal import Credits
 
@@ -78,6 +84,7 @@ class JobBase(BaseModel):
     deviceQrn: str = Field(..., description="qBraid device resource name")
     tags: dict[str, Union[str, int, bool]] = Field(default_factory=dict, description="Job tags")
     runtimeOptions: dict[str, Any] = Field(default_factory=dict, description="Runtime options")
+    groupJobQrn: Optional[str] = Field(None, description="Group job resource name")
 
 
 class JobRequest(JobBase):
@@ -90,7 +97,6 @@ class RuntimeJob(JobBase):
     """Schema for runtime job model"""
 
     jobQrn: str = Field(..., description="qBraid job resource name")
-    batchJobQrn: Optional[str] = Field(None, description="Batch job resource name")
     vendor: Literal["aws", "azure", "ibm", "ionq", "rigetti", "qbraid"] = Field(
         ..., description="Vendor name"
     )

{qbraid_core-0.2.2 → qbraid_core-0.2.3/qbraid_core.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: qbraid-core
-Version: 0.2.2
+Version: 0.2.3
 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.2.2 → qbraid_core-0.2.3}/qbraid_core.egg-info/SOURCES.txt

@@ -52,6 +52,7 @@ qbraid_core/services/runtime/exceptions.py
 qbraid_core/services/runtime/schemas/__init__.py
 qbraid_core/services/runtime/schemas/device.py
 qbraid_core/services/runtime/schemas/enums.py
+qbraid_core/services/runtime/schemas/group.py
 qbraid_core/services/runtime/schemas/job.py
 qbraid_core/services/runtime/schemas/result.py
 qbraid_core/services/storage/__init__.py