openquantum-sdk 0.3.7__tar.gz → 0.4.0__tar.gz

{openquantum_sdk-0.3.7/openquantum_sdk.egg-info → openquantum_sdk-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openquantum-sdk
-Version: 0.3.7
+Version: 0.4.0
 Summary: Python SDK for Open Quantum
 Classifier: Programming Language :: Python :: 3
 Classifier: License :: OSI Approved :: Apache Software License
@@ -9,9 +9,9 @@ Requires-Python: >=3.8
 Description-Content-Type: text/markdown
 Requires-Dist: requests>=2.25.0
 Provides-Extra: qiskit
-Requires-Dist: openquantum-sdk-qiskit>=0.2.4; extra == "qiskit"
+Requires-Dist: openquantum-sdk-qiskit>=0.3.0; extra == "qiskit"
 Provides-Extra: pennylane
-Requires-Dist: openquantum-sdk-pennylane>=0.1.0; extra == "pennylane"
+Requires-Dist: openquantum-sdk-pennylane>=0.2.0; extra == "pennylane"
 
 # Open Quantum Python SDK
 
@@ -21,9 +21,11 @@ A lightweight, modern Python SDK for the **Open Quantum Platform**.
 
 * **Management API** — list organizations, backend classes, and providers
 * **Scheduler API** — job categories, upload, prepare, submit, poll, and **one-call `submit_job()`**
+* **Input formats** — OpenQASM (`qasm`) by default; other formats via `input_format` when the backend supports them
 * **Smart defaults** — auto-select execution plan & queue priority from quote
 * **Thread-safe auth** — Keycloak client-credentials with auto-refresh
 * **Automatic output download** — `download_job_output()` returns parsed JSON
+* **Calibration download** — `download_job_calibration()` when the job has `calibration_data_url`
 
 ## Installation
 
@@ -39,7 +41,7 @@ Python 3.9+ required.
 
 ### Option 1: SDK Key File (Recommended)
 
-Download from [Open Quantum SDK Keys](https://openquantum.com/keys):
+Download from [Open Quantum SDK Keys](https://www.openquantum.com/keys):
 
 ```json
 {
@@ -130,6 +132,11 @@ try:
     else:
         print("No output available.")
 
+    if job.calibration_data_url:
+        cal_json = scheduler.download_job_calibration(job)
+        print("\n--- CALIBRATION (JSON) ---")
+        print(json.dumps(cal_json, indent=2))
+
 except Exception as e:
     print(f"\n--- JOB FAILED ---")
     print(f"Error: {e}")
@@ -273,6 +280,8 @@ finally:
 | `queue_priority` | `QueuePriorityType \| "auto"` | `"auto"` | |
 | `auto_approve_quote` | `bool` | `True` | Set `False` in notebooks |
 | `job_timeout_seconds` | `int` | `86400` | 1 day |
+| `input_format` | `str` | `"qasm"` | OpenQASM by default; other values only if listed in backend `supported_formats` |
+| `submitted_with` | `str` | `"sdk"` | Client surface for analytics |
 
 ## API Reference
 
@@ -291,6 +300,7 @@ finally:
 | `cancel_job(job_id)` | `None` | Cancel running job |
 | `list_jobs(organization_id, limit=20, cursor=..., status=...)` | `PaginatedJobs` | List your jobs |
 | **`download_job_output(job)`** | `Any` | **Downloads + parses JSON output** |
+| **`download_job_calibration(job)`** | `Any` | **Downloads + parses calibration JSON** (when tagged) |
 | `submit_job(config, file_path=... or file_content=...)` | `JobRead` | **One-call submission + polling** |
 
 ### `ManagementClient`
@@ -308,15 +318,15 @@ finally:
 | Model | Key Fields |
 |-------|------------|
 | `BackendClassRead` | `id`, `name`, `description`, `type`, `provider_id`, `short_code`, `queue_depth`, `accepting_jobs`, `status` |
-| `ErrorResponse` | `status_code`, `message: List[str]`, `error_code` |
+| `ErrorResponse` | `status_code`, `message: List[str]`, `type`, `error_code` (request id) |
 | `JobCategoryRead` | `id`, `name`, `short_code` |
 | `JobCreate` | `organization_id`, `job_preparation_id`, `execution_plan_id`, `queue_priority_id` |
-| `JobList` | `id`, `backend_class_id`, `name`, `status`, `backend_name`, `output_data_url`, `credits_used`, `submitted_at` |
-| `JobPreparationCreate` | `organization_id`, `backend_class_id`, `name`, `upload_endpoint_id`, `job_subcategory_id`, `shots`, `configuration_data` |
+| `JobList` | `id`, `backend_class_id`, `name`, `status`, `backend_name`, `output_data_url`, `calibration_data_url`, `credits_used`, `submitted_at` |
+| `JobPreparationCreate` | `organization_id`, `backend_class_id`, `name`, `upload_endpoint_id`, `job_subcategory_id`, `shots`, `configuration_data`, `input_format`, `submitted_with` |
 | `JobPreparationResponse` | `id` |
 | `JobPreparationResultResponse` | `organization_id`, `backend_class_id`, `status`, `name`, `input_data_url`, `job_category_id`, `job_subcategory_id`, `shots`, `quote: List[QuotePlan]`, `message`, `configuration_data` |
 | `JobPreparationUploadResponse` | `id`, `url` |
-| `JobRead` | `id`, `status`, `input_data_url`, `job_preparation_id`, `execution_plan_id`, `queue_priority_id`, `message`, `output_data_url`, `transaction_id`, `submitted_at` |
+| `JobRead` | `id`, `status`, `input_data_url`, `job_preparation_id`, `execution_plan_id`, `queue_priority_id`, `message`, `output_data_url`, `calibration_data_url`, `transaction_id`, `submitted_at` |
 | `OrganizationRead` | `id`, `name` |
 | `PaginatedBackendClasses` | `backend_classes: List[BackendClassRead]`, `pagination: PaginationInfo` |
 | `PaginatedJobCategories` | `categories: List[JobCategoryRead]`, `pagination: PaginationInfo` |

openquantum_sdk-0.3.7/PKG-INFO → openquantum_sdk-0.4.0/README.md

@@ -1,18 +1,3 @@
-Metadata-Version: 2.4
-Name: openquantum-sdk
-Version: 0.3.7
-Summary: Python SDK for Open Quantum
-Classifier: Programming Language :: Python :: 3
-Classifier: License :: OSI Approved :: Apache Software License
-Classifier: Operating System :: OS Independent
-Requires-Python: >=3.8
-Description-Content-Type: text/markdown
-Requires-Dist: requests>=2.25.0
-Provides-Extra: qiskit
-Requires-Dist: openquantum-sdk-qiskit>=0.2.4; extra == "qiskit"
-Provides-Extra: pennylane
-Requires-Dist: openquantum-sdk-pennylane>=0.1.0; extra == "pennylane"
-
 # Open Quantum Python SDK
 
 A lightweight, modern Python SDK for the **Open Quantum Platform**.
@@ -21,9 +6,11 @@ A lightweight, modern Python SDK for the **Open Quantum Platform**.
 
 * **Management API** — list organizations, backend classes, and providers
 * **Scheduler API** — job categories, upload, prepare, submit, poll, and **one-call `submit_job()`**
+* **Input formats** — OpenQASM (`qasm`) by default; other formats via `input_format` when the backend supports them
 * **Smart defaults** — auto-select execution plan & queue priority from quote
 * **Thread-safe auth** — Keycloak client-credentials with auto-refresh
 * **Automatic output download** — `download_job_output()` returns parsed JSON
+* **Calibration download** — `download_job_calibration()` when the job has `calibration_data_url`
 
 ## Installation
 
@@ -39,7 +26,7 @@ Python 3.9+ required.
 
 ### Option 1: SDK Key File (Recommended)
 
-Download from [Open Quantum SDK Keys](https://openquantum.com/keys):
+Download from [Open Quantum SDK Keys](https://www.openquantum.com/keys):
 
 ```json
 {
@@ -130,6 +117,11 @@ try:
     else:
         print("No output available.")
 
+    if job.calibration_data_url:
+        cal_json = scheduler.download_job_calibration(job)
+        print("\n--- CALIBRATION (JSON) ---")
+        print(json.dumps(cal_json, indent=2))
+
 except Exception as e:
     print(f"\n--- JOB FAILED ---")
     print(f"Error: {e}")
@@ -273,6 +265,8 @@ finally:
 | `queue_priority` | `QueuePriorityType \| "auto"` | `"auto"` | |
 | `auto_approve_quote` | `bool` | `True` | Set `False` in notebooks |
 | `job_timeout_seconds` | `int` | `86400` | 1 day |
+| `input_format` | `str` | `"qasm"` | OpenQASM by default; other values only if listed in backend `supported_formats` |
+| `submitted_with` | `str` | `"sdk"` | Client surface for analytics |
 
 ## API Reference
 
@@ -291,6 +285,7 @@ finally:
 | `cancel_job(job_id)` | `None` | Cancel running job |
 | `list_jobs(organization_id, limit=20, cursor=..., status=...)` | `PaginatedJobs` | List your jobs |
 | **`download_job_output(job)`** | `Any` | **Downloads + parses JSON output** |
+| **`download_job_calibration(job)`** | `Any` | **Downloads + parses calibration JSON** (when tagged) |
 | `submit_job(config, file_path=... or file_content=...)` | `JobRead` | **One-call submission + polling** |
 
 ### `ManagementClient`
@@ -308,15 +303,15 @@ finally:
 | Model | Key Fields |
 |-------|------------|
 | `BackendClassRead` | `id`, `name`, `description`, `type`, `provider_id`, `short_code`, `queue_depth`, `accepting_jobs`, `status` |
-| `ErrorResponse` | `status_code`, `message: List[str]`, `error_code` |
+| `ErrorResponse` | `status_code`, `message: List[str]`, `type`, `error_code` (request id) |
 | `JobCategoryRead` | `id`, `name`, `short_code` |
 | `JobCreate` | `organization_id`, `job_preparation_id`, `execution_plan_id`, `queue_priority_id` |
-| `JobList` | `id`, `backend_class_id`, `name`, `status`, `backend_name`, `output_data_url`, `credits_used`, `submitted_at` |
-| `JobPreparationCreate` | `organization_id`, `backend_class_id`, `name`, `upload_endpoint_id`, `job_subcategory_id`, `shots`, `configuration_data` |
+| `JobList` | `id`, `backend_class_id`, `name`, `status`, `backend_name`, `output_data_url`, `calibration_data_url`, `credits_used`, `submitted_at` |
+| `JobPreparationCreate` | `organization_id`, `backend_class_id`, `name`, `upload_endpoint_id`, `job_subcategory_id`, `shots`, `configuration_data`, `input_format`, `submitted_with` |
 | `JobPreparationResponse` | `id` |
 | `JobPreparationResultResponse` | `organization_id`, `backend_class_id`, `status`, `name`, `input_data_url`, `job_category_id`, `job_subcategory_id`, `shots`, `quote: List[QuotePlan]`, `message`, `configuration_data` |
 | `JobPreparationUploadResponse` | `id`, `url` |
-| `JobRead` | `id`, `status`, `input_data_url`, `job_preparation_id`, `execution_plan_id`, `queue_priority_id`, `message`, `output_data_url`, `transaction_id`, `submitted_at` |
+| `JobRead` | `id`, `status`, `input_data_url`, `job_preparation_id`, `execution_plan_id`, `queue_priority_id`, `message`, `output_data_url`, `calibration_data_url`, `transaction_id`, `submitted_at` |
 | `OrganizationRead` | `id`, `name` |
 | `PaginatedBackendClasses` | `backend_classes: List[BackendClassRead]`, `pagination: PaginationInfo` |
 | `PaginatedJobCategories` | `categories: List[JobCategoryRead]`, `pagination: PaginationInfo` |

openquantum_sdk-0.4.0/openquantum_sdk/__init__.py

@@ -0,0 +1,21 @@
+from .clients import SchedulerClient, ManagementClient
+from .models import (
+    APIError,
+    ApiErrorType,
+    TermsOfUseRequiredError,
+    TERMS_OF_USE_REQUIRED_MESSAGE,
+    is_not_found_error,
+)
+from .utils import poll_for_status
+
+__version__ = "0.4.0"
+__all__ = [
+    "SchedulerClient",
+    "ManagementClient",
+    "poll_for_status",
+    "APIError",
+    "ApiErrorType",
+    "TermsOfUseRequiredError",
+    "TERMS_OF_USE_REQUIRED_MESSAGE",
+    "is_not_found_error",
+]

{openquantum_sdk-0.3.7 → openquantum_sdk-0.4.0}/openquantum_sdk/__main__.py

@@ -6,7 +6,8 @@ import json
 import argparse
 import requests
 from .auth import ClientCredentials, ClientCredentialsAuth
-from .clients import APIError, SchedulerClient, ManagementClient, JobSubmissionConfig
+from .clients import SchedulerClient, ManagementClient, JobSubmissionConfig
+from .models import APIError, TermsOfUseRequiredError
 
 
 def load_creds_from_file(path: str) -> ClientCredentials:
@@ -163,12 +164,13 @@ def main():
         print(f"Final Status: {job.status}")
         print(f"Submitted At: {job.submitted_at}")
         print(f"Output URL: {job.output_data_url}")
+        print(f"Calibration URL: {job.calibration_data_url}")
         print("---------------------")
 
         if job.output_data_url:
             print("\nFetching job output...")
             try:
-                output_json = scheduler.download_job_output(job.id)
+                output_json = scheduler.download_job_output(job)
                 print("\n--- JOB OUTPUT (JSON) ---")
                 print(json.dumps(output_json, indent=2))
                 print("-------------------------")
@@ -177,6 +179,19 @@ def main():
         else:
             print("\nNo output_data_url available (job may have failed or produced no output).")
 
+        if job.calibration_data_url:
+            print("\nFetching calibration data...")
+            try:
+                cal_json = scheduler.download_job_calibration(job)
+                print("\n--- CALIBRATION (JSON) ---")
+                print(json.dumps(cal_json, indent=2))
+                print("--------------------------")
+            except Exception as e:
+                print(f"Failed to download/parse calibration: {e}", file=sys.stderr)
+
+    except TermsOfUseRequiredError as e:
+        print(str(e), file=sys.stderr)
+        sys.exit(1)
     except requests.exceptions.HTTPError as e:
         print(f"API error: {e.response.status_code} - {e.response.text}", file=sys.stderr)
         sys.exit(1)

{openquantum_sdk-0.3.7 → openquantum_sdk-0.4.0}/openquantum_sdk/backends.py

@@ -67,6 +67,9 @@ class BackendCapabilities:
             "verbatim_boxes", ...). See sdk/docs/device-features.md and
             the DeviceFeatures enum. These drive precompilation,
             validation, and SDK-side decisions before jobs reach QPUs.
+        supported_formats: Circuit input language families this backend
+            accepts (e.g. ``"qasm"``, ``"qblox_sequence"``). Defaults to
+            ``["qasm"]``. OpenQASM 2 and 3 both map to ``"qasm"``.
     """
 
     short_code: str
@@ -76,6 +79,7 @@ class BackendCapabilities:
     topology: Topology = field(default_factory=Topology)
     limits: Dict[str, Any] = field(default_factory=dict)
     features: List[str] = field(default_factory=list)
+    supported_formats: List[str] = field(default_factory=lambda: ["qasm"])
 
     @property
     def supported_gate_names(self) -> set[str]:
@@ -136,6 +140,11 @@ class BackendCapabilities:
         """True if classical control flow (if/for/while on classical bits) is supported."""
         return self.supports_feature("classical_control")
 
+    def supports_format(self, name: str) -> bool:
+        """Return True if the backend accepts the given input format family."""
+        formats = self.supported_formats or ["qasm"]
+        return name in formats
+
     def to_dict(self) -> Dict[str, Any]:
         """Convert to the dict format used by the Qiskit plugin's target builder."""
         return {
@@ -148,6 +157,9 @@ class BackendCapabilities:
             "noise": {},
             "limits": self.limits,
             "features": list(self.features) if self.features else ["measure"],
+            "supported_formats": list(self.supported_formats)
+            if self.supported_formats
+            else ["qasm"],
         }
 
 
@@ -624,6 +636,11 @@ def capabilities_from_constraint_data(
         directed_edges=topo_data.get("directed_edges", False),
         coupling_map=topo_data.get("coupling_map", []),
     )
+    raw_formats = constraint_data.get("supported_formats") or []
+    supported_formats = (
+        [str(f) for f in raw_formats] if raw_formats else ["qasm"]
+    )
+
     return BackendCapabilities(
         short_code=short_code,
         n_qubits=constraint_data.get("n_qubits", 0),
@@ -632,6 +649,7 @@ def capabilities_from_constraint_data(
         topology=topology,
         limits=constraint_data.get("limits", {}),
         features=constraint_data.get("features", []) or [],
+        supported_formats=supported_formats,
     )
 
 

{openquantum_sdk-0.3.7 → openquantum_sdk-0.4.0}/openquantum_sdk/clients.py

@@ -11,6 +11,9 @@ from .enums import AutoChoice, ExecutionPlanType, QueuePriorityType
 from .utils import strip_gate_definitions
 from .models import (
     APIError,
+    TermsOfUseRequiredError,
+    error_from_response,
+    is_not_found_error,
     BackendClassRead,
     CreditBalanceRead,
     ErrorResponse,
@@ -66,6 +69,12 @@ class JobSubmissionConfig:
             submission. Useful in notebooks and CLI scripts.
         job_timeout_seconds: Maximum seconds to wait for the job to complete.
             Defaults to 86 400 (1 day).
+        submitted_with: Client/surface that submitted this preparation
+            (e.g. ``"sdk"``, ``"qiskit"``, ``"cli"``). Defaults to ``"sdk"``.
+        input_format: Circuit input language family (``"qasm"`` or
+            ``"qblox_sequence"``). Defaults to ``"qasm"``. OpenQASM 2/3
+            both use ``"qasm"``; use ``"qblox_sequence"`` for Qblox
+            sequencer JSON (program + waveforms).
 
     Example:
         >>> config = JobSubmissionConfig(
@@ -93,6 +102,12 @@ class JobSubmissionConfig:
     # USER-CONTROLLABLE: How long to wait for job to finish
     job_timeout_seconds: int = 86_400  # 1 day
 
+    # Attribution for analytics / provenance
+    submitted_with: Optional[str] = "sdk"
+
+    # Circuit language family (qasm | qblox_sequence). None → API default "qasm".
+    input_format: Optional[str] = None
+
     # INTERNAL: Fixed preparation timeout and polling
     _preparation_timeout_seconds: int = 300  # 5 minutes
     _preparation_poll_interval: float = 2.0
@@ -159,9 +174,12 @@ class BaseClient:
                     err = ErrorResponse(
                         status_code=payload.get("status_code", resp.status_code),
                         message=payload.get("message", []),
+                        type=payload.get("type"),
                         error_code=payload.get("error_code"),
                     )
-                    raise APIError(err)
+                    raise error_from_response(err)
+            except (TermsOfUseRequiredError, APIError):
+                raise
             except ValueError:
                 pass
             resp.raise_for_status()
@@ -422,6 +440,39 @@ class SchedulerClient(BaseClient):
                 "Content may not be JSON or is malformed."
             ) from exc
 
+    def download_job_calibration(self, job: JobRead) -> Any:
+        """Download and parse the calibration snapshot tagged on a job.
+
+        Calibration is optional: only present if reported.
+
+        Args:
+            job: A ``JobRead`` from ``get_job`` / ``submit_job``. Must have a
+                non-``None`` ``calibration_data_url``.
+
+        Returns:
+            Parsed JSON calibration payload.
+
+        Raises:
+            RuntimeError: If the job has no ``calibration_data_url``.
+            ValueError: If the body cannot be parsed as JSON.
+        """
+        if not job.calibration_data_url:
+            raise RuntimeError(
+                f"Job {job.id} has no calibration_data_url. "
+                "No calibration was tagged on the completing execution."
+            )
+
+        resp = requests.get(job.calibration_data_url)
+        resp.raise_for_status()
+
+        try:
+            return resp.json()
+        except ValueError as exc:
+            raise ValueError(
+                f"Failed to parse calibration of job {job.id} as JSON. "
+                "Content may not be JSON or is malformed."
+            ) from exc
+
     def prepare_job(self, preparation: JobPreparationCreate) -> JobPreparationResponse:
         """Submit a job preparation request.
 
@@ -435,7 +486,12 @@ class SchedulerClient(BaseClient):
         Returns:
             A ``JobPreparationResponse`` containing the preparation ``id``.
         """
-        data = self._request("POST", "/v1/jobs/prepare", json=asdict(preparation))
+        payload = {
+            key: value
+            for key, value in asdict(preparation).items()
+            if value is not None
+        }
+        data = self._request("POST", "/v1/jobs/prepare", json=payload)
         return JobPreparationResponse.from_dict(data)
 
     def get_preparation_result(self, preparation_id: str) -> JobPreparationResultResponse:
@@ -496,6 +552,7 @@ class SchedulerClient(BaseClient):
             message=data.get("message"),
             quote=quote,
             configuration_data=data.get("configuration_data", {}),
+            input_format=data.get("input_format"),
         )
 
     def create_job(self, job: JobCreate) -> JobRead:
@@ -651,6 +708,8 @@ class SchedulerClient(BaseClient):
             job_subcategory_id=config.job_subcategory_id,
             shots=config.shots,
             configuration_data=config.configuration_data or {},
+            submitted_with=config.submitted_with,
+            input_format=config.input_format,
         )
         if config.verbose:
             print("Step 2/5: Preparing job and fetching quote...")
@@ -749,7 +808,7 @@ class SchedulerClient(BaseClient):
                 done = resp.status in ("Completed", "Failed")
                 return done, resp
             except APIError as e:
-                if e.error_response.status_code == 404:
+                if is_not_found_error(e):
                     if verbose:
                         print("  > Preparation status: Not found (retrying...)")
                     return False, None

{openquantum_sdk-0.3.7 → openquantum_sdk-0.4.0}/openquantum_sdk/models.py

@@ -50,6 +50,24 @@ class PaginationInfo(FlexibleDataclass):
     extra: Dict[str, Any] = field(default_factory=dict, repr=False)
 
 
+class ApiErrorType:
+    UNAUTHORIZED = "UNAUTHORIZED"
+    FORBIDDEN = "FORBIDDEN"
+    INSUFFICIENT_PERMISSIONS = "INSUFFICIENT_PERMISSIONS"
+    ORG_MEMBERSHIP_REQUIRED = "ORG_MEMBERSHIP_REQUIRED"
+    TERMS_OF_USE_REQUIRED = "TERMS_OF_USE_REQUIRED"
+    NOT_FOUND = "NOT_FOUND"
+    CONFLICT = "CONFLICT"
+    VALIDATION_ERROR = "VALIDATION_ERROR"
+    BAD_REQUEST = "BAD_REQUEST"
+    INSUFFICIENT_CREDITS = "INSUFFICIENT_CREDITS"
+    JOB_LIMIT_REACHED = "JOB_LIMIT_REACHED"
+    JOB_NOT_CANCELABLE = "JOB_NOT_CANCELABLE"
+    RESOURCE_NOT_ACTIVE = "RESOURCE_NOT_ACTIVE"
+    NOT_READY = "NOT_READY"
+    INTERNAL_ERROR = "INTERNAL_ERROR"
+
+
 @dataclass
 class ErrorResponse:
     """Structured error payload returned by the API on HTTP 4xx/5xx responses.
@@ -57,11 +75,13 @@ class ErrorResponse:
     Attributes:
         status_code: The HTTP status code from the response.
         message: List of human-readable error message strings.
-        error_code: Optional request/error identifier for support tracing.
+        type: Stable machine-readable error type (see ``ApiErrorType``).
+        error_code: Request identifier for support tracing.
     """
 
     status_code: int
     message: Union[List[str], str]
+    type: Optional[str] = None
     error_code: Optional[str] = None
 
 
@@ -79,7 +99,59 @@ class APIError(Exception):
         self.error_response = error_response
         msgs = error_response.message if isinstance(error_response.message, list) else [error_response.message]
         msg = "; ".join(msgs)
-        super().__init__(f"API Error {error_response.status_code}: {msg} (Request ID: {error_response.error_code})")
+        type_part = f" [{error_response.type}]" if error_response.type else ""
+        super().__init__(
+            f"API Error {error_response.status_code}{type_part}: {msg} "
+            f"(Request ID: {error_response.error_code})"
+        )
+
+
+TERMS_OF_USE_REQUIRED_MESSAGE = (
+    "Please visit https://www.openquantum.com to accept the Terms of Use before submitting jobs."
+)
+
+
+class TermsOfUseRequiredError(APIError):
+    """Raised when job prepare/create is blocked until Terms of Use are accepted.
+
+    Users must visit https://www.openquantum.com, sign in, and accept the latest
+    Terms of Use (and complete portal onboarding) before submitting jobs.
+    """
+
+    def __init__(self, error_response: Optional[ErrorResponse] = None):
+        if error_response is None:
+            error_response = ErrorResponse(
+                status_code=403,
+                message=TERMS_OF_USE_REQUIRED_MESSAGE,
+                type=ApiErrorType.TERMS_OF_USE_REQUIRED,
+            )
+        # Keep error_response for callers that inspect status/request id, but
+        # present a clean, actionable message (not the generic API Error wrapper).
+        self.error_response = error_response
+        Exception.__init__(self, TERMS_OF_USE_REQUIRED_MESSAGE)
+
+
+def error_from_response(error_response: ErrorResponse) -> APIError:
+    """Map an API ``ErrorResponse`` to the most specific SDK exception.
+
+    Branching uses the stable ``type`` field only — never message text.
+    """
+    if error_response.type == ApiErrorType.TERMS_OF_USE_REQUIRED:
+        return TermsOfUseRequiredError(error_response)
+    return APIError(error_response)
+
+
+def is_not_found_error(error: APIError) -> bool:
+    """Return True if the error indicates a missing resource.
+
+    Prefers ``ErrorResponse.type``; falls back to HTTP 404 when ``type``
+    is absent (e.g. older gateways).
+    """
+    if error.error_response.type == ApiErrorType.NOT_FOUND:
+        return True
+    if error.error_response.type is None and error.error_response.status_code == 404:
+        return True
+    return False
 
 
 # ---------------------------------------------------------------------------
@@ -253,6 +325,14 @@ class JobPreparationCreate:
         job_subcategory_id: Job subcategory UUID or short code.
         shots: Number of measurement shots to execute.
         configuration_data: Optional backend-specific configuration.
+        submitted_with: Client/surface that submitted this preparation
+            (e.g. ``"sdk"``, ``"qiskit"``, ``"pennylane"``, ``"cli"``).
+            Optional; omit or ``None`` for unknown/legacy clients.
+        input_format: Circuit input language family (``"qasm"`` or
+            ``"qblox_sequence"``). Defaults to ``"qasm"``. OpenQASM 2 and
+            3 both use ``"qasm"``; version is detected from the file.
+            ``"qblox_sequence"`` is Qblox sequencer JSON. Must be listed
+            in the backend's ``constraint_data.supported_formats``.
     """
 
     organization_id: str
@@ -262,6 +342,8 @@ class JobPreparationCreate:
     job_subcategory_id: str
     shots: int
     configuration_data: Dict[str, Any] = field(default_factory=dict)
+    submitted_with: Optional[str] = None
+    input_format: Optional[str] = None
 
 
 @dataclass
@@ -355,6 +437,8 @@ class JobPreparationResultResponse:
         quote: List of available execution plans with pricing details.
         message: Optional status or error message.
         configuration_data: Backend-specific configuration echoed back.
+        input_format: Circuit input language family (``"qasm"`` or
+            ``"qblox_sequence"``).
         extra: Additional fields returned by the API not mapped to attributes.
     """
 
@@ -369,6 +453,7 @@ class JobPreparationResultResponse:
     quote: List[QuotePlan]
     message: Optional[str] = None
     configuration_data: Dict[str, Any] = field(default_factory=dict)
+    input_format: Optional[str] = None
     extra: Dict[str, Any] = field(default_factory=dict, repr=False)
 
 
@@ -406,6 +491,8 @@ class JobRead(FlexibleDataclass):
         message: Optional status or error message from the backend.
         output_data_url: URL to download results from, available once
             the job completes.
+        calibration_data_url: Presigned URL for the calibration snapshot
+            tagged on the successful execution, if any.
         transaction_id: Credit transaction ID, if a charge was applied.
         submitted_at: ISO 8601 timestamp of when the job was submitted.
         extra: Additional fields returned by the API not mapped to attributes.
@@ -419,6 +506,7 @@ class JobRead(FlexibleDataclass):
     queue_priority_id: str
     message: Optional[str] = None
     output_data_url: Optional[str] = None
+    calibration_data_url: Optional[str] = None
     transaction_id: Optional[str] = None
     submitted_at: Optional[str] = None
     extra: Dict[str, Any] = field(default_factory=dict, repr=False)
@@ -438,6 +526,8 @@ class JobList(FlexibleDataclass):
         status: Current job status string.
         backend_name: Display name of the backend, if available.
         output_data_url: URL to download results, if the job completed.
+        calibration_data_url: Presigned URL for the calibration snapshot
+            tagged on the successful execution, if any.
         credits_used: Number of credits charged for this job.
         submitted_at: ISO 8601 timestamp of when the job was submitted.
         extra: Additional fields returned by the API not mapped to attributes.
@@ -449,6 +539,7 @@ class JobList(FlexibleDataclass):
     status: str
     backend_name: Optional[str] = None
     output_data_url: Optional[str] = None
+    calibration_data_url: Optional[str] = None
     credits_used: Optional[float] = None
     submitted_at: Optional[str] = None
     extra: Dict[str, Any] = field(default_factory=dict, repr=False)

openquantum_sdk-0.3.7/README.md → openquantum_sdk-0.4.0/openquantum_sdk.egg-info/PKG-INFO

@@ -1,3 +1,18 @@
+Metadata-Version: 2.4
+Name: openquantum-sdk
+Version: 0.4.0
+Summary: Python SDK for Open Quantum
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.25.0
+Provides-Extra: qiskit
+Requires-Dist: openquantum-sdk-qiskit>=0.3.0; extra == "qiskit"
+Provides-Extra: pennylane
+Requires-Dist: openquantum-sdk-pennylane>=0.2.0; extra == "pennylane"
+
 # Open Quantum Python SDK
 
 A lightweight, modern Python SDK for the **Open Quantum Platform**.
@@ -6,9 +21,11 @@ A lightweight, modern Python SDK for the **Open Quantum Platform**.
 
 * **Management API** — list organizations, backend classes, and providers
 * **Scheduler API** — job categories, upload, prepare, submit, poll, and **one-call `submit_job()`**
+* **Input formats** — OpenQASM (`qasm`) by default; other formats via `input_format` when the backend supports them
 * **Smart defaults** — auto-select execution plan & queue priority from quote
 * **Thread-safe auth** — Keycloak client-credentials with auto-refresh
 * **Automatic output download** — `download_job_output()` returns parsed JSON
+* **Calibration download** — `download_job_calibration()` when the job has `calibration_data_url`
 
 ## Installation
 
@@ -24,7 +41,7 @@ Python 3.9+ required.
 
 ### Option 1: SDK Key File (Recommended)
 
-Download from [Open Quantum SDK Keys](https://openquantum.com/keys):
+Download from [Open Quantum SDK Keys](https://www.openquantum.com/keys):
 
 ```json
 {
@@ -115,6 +132,11 @@ try:
     else:
         print("No output available.")
 
+    if job.calibration_data_url:
+        cal_json = scheduler.download_job_calibration(job)
+        print("\n--- CALIBRATION (JSON) ---")
+        print(json.dumps(cal_json, indent=2))
+
 except Exception as e:
     print(f"\n--- JOB FAILED ---")
     print(f"Error: {e}")
@@ -258,6 +280,8 @@ finally:
 | `queue_priority` | `QueuePriorityType \| "auto"` | `"auto"` | |
 | `auto_approve_quote` | `bool` | `True` | Set `False` in notebooks |
 | `job_timeout_seconds` | `int` | `86400` | 1 day |
+| `input_format` | `str` | `"qasm"` | OpenQASM by default; other values only if listed in backend `supported_formats` |
+| `submitted_with` | `str` | `"sdk"` | Client surface for analytics |
 
 ## API Reference
 
@@ -276,6 +300,7 @@ finally:
 | `cancel_job(job_id)` | `None` | Cancel running job |
 | `list_jobs(organization_id, limit=20, cursor=..., status=...)` | `PaginatedJobs` | List your jobs |
 | **`download_job_output(job)`** | `Any` | **Downloads + parses JSON output** |
+| **`download_job_calibration(job)`** | `Any` | **Downloads + parses calibration JSON** (when tagged) |
 | `submit_job(config, file_path=... or file_content=...)` | `JobRead` | **One-call submission + polling** |
 
 ### `ManagementClient`
@@ -293,15 +318,15 @@ finally:
 | Model | Key Fields |
 |-------|------------|
 | `BackendClassRead` | `id`, `name`, `description`, `type`, `provider_id`, `short_code`, `queue_depth`, `accepting_jobs`, `status` |
-| `ErrorResponse` | `status_code`, `message: List[str]`, `error_code` |
+| `ErrorResponse` | `status_code`, `message: List[str]`, `type`, `error_code` (request id) |
 | `JobCategoryRead` | `id`, `name`, `short_code` |
 | `JobCreate` | `organization_id`, `job_preparation_id`, `execution_plan_id`, `queue_priority_id` |
-| `JobList` | `id`, `backend_class_id`, `name`, `status`, `backend_name`, `output_data_url`, `credits_used`, `submitted_at` |
-| `JobPreparationCreate` | `organization_id`, `backend_class_id`, `name`, `upload_endpoint_id`, `job_subcategory_id`, `shots`, `configuration_data` |
+| `JobList` | `id`, `backend_class_id`, `name`, `status`, `backend_name`, `output_data_url`, `calibration_data_url`, `credits_used`, `submitted_at` |
+| `JobPreparationCreate` | `organization_id`, `backend_class_id`, `name`, `upload_endpoint_id`, `job_subcategory_id`, `shots`, `configuration_data`, `input_format`, `submitted_with` |
 | `JobPreparationResponse` | `id` |
 | `JobPreparationResultResponse` | `organization_id`, `backend_class_id`, `status`, `name`, `input_data_url`, `job_category_id`, `job_subcategory_id`, `shots`, `quote: List[QuotePlan]`, `message`, `configuration_data` |
 | `JobPreparationUploadResponse` | `id`, `url` |
-| `JobRead` | `id`, `status`, `input_data_url`, `job_preparation_id`, `execution_plan_id`, `queue_priority_id`, `message`, `output_data_url`, `transaction_id`, `submitted_at` |
+| `JobRead` | `id`, `status`, `input_data_url`, `job_preparation_id`, `execution_plan_id`, `queue_priority_id`, `message`, `output_data_url`, `calibration_data_url`, `transaction_id`, `submitted_at` |
 | `OrganizationRead` | `id`, `name` |
 | `PaginatedBackendClasses` | `backend_classes: List[BackendClassRead]`, `pagination: PaginationInfo` |
 | `PaginatedJobCategories` | `categories: List[JobCategoryRead]`, `pagination: PaginationInfo` |

openquantum_sdk-0.4.0/openquantum_sdk.egg-info/requires.txt

@@ -0,0 +1,7 @@
+requests>=2.25.0
+
+[pennylane]
+openquantum-sdk-pennylane>=0.2.0
+
+[qiskit]
+openquantum-sdk-qiskit>=0.3.0

{openquantum_sdk-0.3.7 → openquantum_sdk-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "openquantum-sdk"
-version = "0.3.7"
+version = "0.4.0"
 description = "Python SDK for Open Quantum"
 readme = "README.md"
 requires-python = ">=3.8"
@@ -19,8 +19,8 @@ classifiers = [
 ]
 
 [project.optional-dependencies]
-qiskit = ["openquantum-sdk-qiskit>=0.2.4"]
-pennylane = ["openquantum-sdk-pennylane>=0.1.0"]
+qiskit = ["openquantum-sdk-qiskit>=0.3.0"]
+pennylane = ["openquantum-sdk-pennylane>=0.2.0"]
 
 [project.scripts]
 openquantum-sdk = "openquantum_sdk.__main__:main"

{openquantum_sdk-0.3.7 → openquantum_sdk-0.4.0}/tests/test_backends.py

@@ -189,6 +189,23 @@ class TestBackendFeatures:
         assert caps.allows_barriers is True
         assert caps.allows_reset is False
         assert caps.allows_dynamic_circuits is False
+        # Missing supported_formats defaults to qasm
+        assert caps.supported_formats == ["qasm"]
+        assert caps.supports_format("qasm") is True
+        assert caps.supports_format("qblox_sequence") is False
+
+    def test_capabilities_from_constraint_data_parses_supported_formats(self):
+        cd = {
+            "n_qubits": 8,
+            "native_ops": [],
+            "topology": {"directed_edges": False, "coupling_map": []},
+            "supported_formats": ["qblox_sequence"],
+        }
+        caps = capabilities_from_constraint_data("test:qblox", cd)
+        assert caps.supported_formats == ["qblox_sequence"]
+        assert caps.supports_format("qblox_sequence") is True
+        assert caps.supports_format("qasm") is False
+        assert caps.to_dict()["supported_formats"] == ["qblox_sequence"]
 
     def test_features_helpers_on_live_style_data(self):
         cd = {

{openquantum_sdk-0.3.7 → openquantum_sdk-0.4.0}/tests/test_clients.py

@@ -13,10 +13,13 @@ from openquantum_sdk.clients import (
 )
 from openquantum_sdk.enums import ExecutionPlanType, QueuePriorityType
 from openquantum_sdk.models import (
+    JobCreate,
     QuotePlan,
     QueuePriority,
     JobPreparationCreate,
     OrganizationRead,
+    TERMS_OF_USE_REQUIRED_MESSAGE,
+    TermsOfUseRequiredError,
 )
 
 
@@ -54,6 +57,7 @@ def mock_scheduler():
                 "queue_priority_id": "prio-1",
                 "input_data_url": "https://input.example.com/job-123",
                 "output_data_url": "https://output.example.com/result-123",
+                "calibration_data_url": "https://calibration.example.com/cal-123",
                 "transaction_id": "tx-789",
                 "submitted_at": "2025-04-05T12:00:00Z",
             },
@@ -425,6 +429,26 @@ def test_download_job_output_non_json(mock_scheduler):
         mock_scheduler.download_job_output(job)
 
 
+def test_download_job_calibration_success(mock_scheduler):
+    m = mock_scheduler.session.mocker
+    m.get(
+        "https://calibration.example.com/cal-123",
+        json={"classifiers": {}, "components": {}},
+    )
+    job = mock_scheduler.get_job("job-123")
+    # Inject calibration URL as API would after completion
+    job.calibration_data_url = "https://calibration.example.com/cal-123"
+    cal = mock_scheduler.download_job_calibration(job)
+    assert "classifiers" in cal
+
+
+def test_download_job_calibration_no_url(mock_scheduler):
+    job = mock_scheduler.get_job("job-123")
+    job.calibration_data_url = None
+    with pytest.raises(RuntimeError, match=r"no calibration_data_url"):
+        mock_scheduler.download_job_calibration(job)
+
+
 def test_download_job_output_http_error(mock_scheduler):
     job = mock_scheduler.get_job("job-123")
     mock_scheduler.session.mocker.get(
@@ -436,6 +460,85 @@ def test_download_job_output_http_error(mock_scheduler):
         mock_scheduler.download_job_output(job)
 
 
+def test_prepare_job_terms_of_use_required(mock_scheduler):
+    mock_scheduler.session.mocker.post(
+        "https://scheduler.openquantum.com/v1/jobs/prepare",
+        status_code=403,
+        json={
+            "status_code": 403,
+            "message": [TERMS_OF_USE_REQUIRED_MESSAGE],
+            "type": "TERMS_OF_USE_REQUIRED",
+            "error_code": "req-terms",
+        },
+    )
+    prep = JobPreparationCreate(
+        organization_id="org-123",
+        backend_class_id="backend-1",
+        name="Test",
+        upload_endpoint_id="upload-1",
+        job_subcategory_id="sub-1",
+        shots=10,
+        configuration_data={},
+    )
+    with pytest.raises(TermsOfUseRequiredError, match="openquantum.com") as exc_info:
+        mock_scheduler.prepare_job(prep)
+    assert str(exc_info.value) == TERMS_OF_USE_REQUIRED_MESSAGE
+    assert exc_info.value.error_response.status_code == 403
+    assert exc_info.value.error_response.type == "TERMS_OF_USE_REQUIRED"
+
+
+def test_create_job_terms_of_use_required(mock_scheduler):
+    mock_scheduler.session.mocker.post(
+        "https://scheduler.openquantum.com/v1/jobs",
+        status_code=403,
+        json={
+            "status_code": 403,
+            "message": TERMS_OF_USE_REQUIRED_MESSAGE,
+            "type": "TERMS_OF_USE_REQUIRED",
+            "error_code": "req-terms",
+        },
+    )
+    job = JobCreate(
+        organization_id="org-123",
+        job_preparation_id="prep-1",
+        execution_plan_id="plan-1",
+        queue_priority_id="prio-1",
+    )
+    with pytest.raises(TermsOfUseRequiredError, match="Terms of Use"):
+        mock_scheduler.create_job(job)
+
+
+def test_prepare_job_org_membership_required(mock_scheduler):
+    from openquantum_sdk.models import APIError, ApiErrorType
+
+    mock_scheduler.session.mocker.post(
+        "https://scheduler.openquantum.com/v1/jobs/prepare",
+        status_code=403,
+        json={
+            "status_code": 403,
+            "message": ["User is not a member of the organization"],
+            "type": ApiErrorType.ORG_MEMBERSHIP_REQUIRED,
+            "error_code": "req-org",
+        },
+    )
+    prep = JobPreparationCreate(
+        organization_id="org-123",
+        backend_class_id="backend-1",
+        name="Test",
+        upload_endpoint_id="upload-1",
+        job_subcategory_id="sub-1",
+        shots=10,
+        configuration_data={},
+    )
+    with pytest.raises(APIError) as exc_info:
+        mock_scheduler.prepare_job(prep)
+    assert not isinstance(exc_info.value, TermsOfUseRequiredError)
+    assert (
+        exc_info.value.error_response.type
+        == ApiErrorType.ORG_MEMBERSHIP_REQUIRED
+    )
+
+
 # ---------------------------------------------------------------------------
 # Categories & Listing
 # ---------------------------------------------------------------------------

openquantum_sdk-0.3.7/openquantum_sdk/__init__.py

@@ -1,5 +0,0 @@
-from .clients import SchedulerClient, ManagementClient
-from .utils import poll_for_status
-
-__version__ = "0.3.7"
-__all__ = ["SchedulerClient", "ManagementClient", "poll_for_status"]

openquantum_sdk-0.3.7/openquantum_sdk.egg-info/requires.txt

@@ -1,7 +0,0 @@
-requests>=2.25.0
-
-[pennylane]
-openquantum-sdk-pennylane>=0.1.0
-
-[qiskit]
-openquantum-sdk-qiskit>=0.2.4