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

{openquantum_sdk-0.3.4/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.4
+Version: 0.4.0
 Summary: Python SDK for Open Quantum
 Classifier: Programming Language :: Python :: 3
 Classifier: License :: OSI Approved :: Apache Software License
@@ -8,6 +8,10 @@ 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
 
@@ -17,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
 
@@ -35,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
 {
@@ -100,7 +106,7 @@ try:
     # 3. Define config
     config = JobSubmissionConfig(
         organization_id=org_id,
-        backend_class_id="rigetti:ankaa-3",
+        backend_class_id="iqm:emerald",
         name="Bell State SDK Quickstart",
         job_subcategory_id="fin:port", # Finance Portfolio Optimization
         shots=100,
@@ -126,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}")
@@ -162,7 +173,7 @@ try:
         print(f" - {bc.name} [{bc.type}] — {bc.short_code or bc.id}")
 
     # 2. Choose IDs
-    MY_BACKEND = "rigetti:ankaa-3"
+    MY_BACKEND = "iqm:emerald"
     MY_SUBCATEGORY = "fin:port"
 
     # 3. Upload
@@ -269,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
 
@@ -287,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`
@@ -304,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` |
@@ -353,7 +367,7 @@ from openquantum_sdk.enums import ExecutionPlanType, QueuePriorityType
 ```bash
 python -m openquantum_sdk --sdk-key ./key.json \
                           --input bell.qasm \
-                          --backend "ionq:aria-1" \
+                          --backend "iqm:emerald" \
                           --name "CLI Circuit" \
                           --subcategory "mathematics:linear-systems" \
                           --shots 100 \
@@ -367,11 +381,12 @@ Automatically **downloads and pretty-prints JSON output**.
 ### Backends 
 | Provider | Backend |  Short Code | 
 | ------ | ------ | ------ |
-| IonQ | Aria-1 | `ionq:aria-1` |
+| AQT | Ibex-Q1 | `aqt:ibex-q1` |
+| IonQ | Forte Enterprise | `ionq:forte-ent` |
 | IonQ | Forte-1 | `ionq:forte-1` |
 | IQM | Emerald | `iqm:emerald` |
 | IQM | Garnet | `iqm:garnet` | 
-| Rigetti | Ankaa-3 | `rigetti:ankaa-3` |
+| Rigetti | Cepheus-1-108Q | `rigetti:cepheus-108q`|
 
 *Note: This list may be modified as backends are added or removed from the platform. For the most up-to-date list, run the following code:*
 
@@ -439,8 +454,8 @@ for cat in cats:
 **Q: How do I get results as JSON?**  
 **A:** Use `scheduler.download_job_output(job)` — returns parsed object.
 
-**Q: Why does auto mode fail on some QPUs?**  
-**A:** `auto` only allows `PUBLIC` + `STANDARD`. Use explicit enums for private/instant access.
+**Q: Why does auto mode fail on some QPUs?**
+**A:** `"auto"` selects the cheapest plan and priority (`PUBLIC` + `STANDARD`). If a backend only offers private execution, pass `execution_plan="private"` explicitly. Similarly, use `queue_priority="priority"` or `"instant"` for higher-priority queue access.
 
 **Q: Can I hide the public plan citation notice?**  
 **A:** Setting `OPENQUANTUM_HIDE_CITATION_NOTICE=true` will omit the citation notice from output.

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

@@ -1,14 +1,3 @@
-Metadata-Version: 2.4
-Name: openquantum-sdk
-Version: 0.3.4
-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
-
 # Open Quantum Python SDK
 
 A lightweight, modern Python SDK for the **Open Quantum Platform**.
@@ -17,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
 
@@ -35,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
 {
@@ -100,7 +91,7 @@ try:
     # 3. Define config
     config = JobSubmissionConfig(
         organization_id=org_id,
-        backend_class_id="rigetti:ankaa-3",
+        backend_class_id="iqm:emerald",
         name="Bell State SDK Quickstart",
         job_subcategory_id="fin:port", # Finance Portfolio Optimization
         shots=100,
@@ -126,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}")
@@ -162,7 +158,7 @@ try:
         print(f" - {bc.name} [{bc.type}] — {bc.short_code or bc.id}")
 
     # 2. Choose IDs
-    MY_BACKEND = "rigetti:ankaa-3"
+    MY_BACKEND = "iqm:emerald"
     MY_SUBCATEGORY = "fin:port"
 
     # 3. Upload
@@ -269,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
 
@@ -287,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`
@@ -304,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` |
@@ -353,7 +352,7 @@ from openquantum_sdk.enums import ExecutionPlanType, QueuePriorityType
 ```bash
 python -m openquantum_sdk --sdk-key ./key.json \
                           --input bell.qasm \
-                          --backend "ionq:aria-1" \
+                          --backend "iqm:emerald" \
                           --name "CLI Circuit" \
                           --subcategory "mathematics:linear-systems" \
                           --shots 100 \
@@ -367,11 +366,12 @@ Automatically **downloads and pretty-prints JSON output**.
 ### Backends 
 | Provider | Backend |  Short Code | 
 | ------ | ------ | ------ |
-| IonQ | Aria-1 | `ionq:aria-1` |
+| AQT | Ibex-Q1 | `aqt:ibex-q1` |
+| IonQ | Forte Enterprise | `ionq:forte-ent` |
 | IonQ | Forte-1 | `ionq:forte-1` |
 | IQM | Emerald | `iqm:emerald` |
 | IQM | Garnet | `iqm:garnet` | 
-| Rigetti | Ankaa-3 | `rigetti:ankaa-3` |
+| Rigetti | Cepheus-1-108Q | `rigetti:cepheus-108q`|
 
 *Note: This list may be modified as backends are added or removed from the platform. For the most up-to-date list, run the following code:*
 
@@ -439,8 +439,8 @@ for cat in cats:
 **Q: How do I get results as JSON?**  
 **A:** Use `scheduler.download_job_output(job)` — returns parsed object.
 
-**Q: Why does auto mode fail on some QPUs?**  
-**A:** `auto` only allows `PUBLIC` + `STANDARD`. Use explicit enums for private/instant access.
+**Q: Why does auto mode fail on some QPUs?**
+**A:** `"auto"` selects the cheapest plan and priority (`PUBLIC` + `STANDARD`). If a backend only offers private execution, pass `execution_plan="private"` explicitly. Similarly, use `queue_priority="priority"` or `"instant"` for higher-priority queue access.
 
 **Q: Can I hide the public plan citation notice?**  
 **A:** Setting `OPENQUANTUM_HIDE_CITATION_NOTICE=true` will omit the citation notice from output.

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.4 → 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:
@@ -121,8 +122,10 @@ def main():
         creds=creds
     )
 
-    scheduler = SchedulerClient(base_url=args.scheduler_base, auth=auth)
     management = ManagementClient(base_url=args.management_base, auth=auth)
+    scheduler = SchedulerClient(
+        base_url=args.scheduler_base, auth=auth, management_client=management
+    )
 
     try:
         print("--- Open Quantum Job Submission CLI ---")
@@ -161,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("-------------------------")
@@ -175,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.4 → openquantum_sdk-0.4.0}/openquantum_sdk/auth.py

@@ -9,17 +9,28 @@ from urllib.parse import urljoin
 
 @dataclass
 class ClientCredentials:
+    """SDK key credentials for machine-to-machine authentication.
+
+    Attributes:
+        client_id: The OAuth2 client ID (SDK key ID).
+        client_secret: The OAuth2 client secret (SDK key secret).
+    """
+
     client_id: str
     client_secret: str
 
 
 class ClientCredentialsAuth:
+    """Keycloak client-credentials OAuth2 helper with thread-safe token caching.
+
+    Manages the full token lifecycle: initial fetch, automatic refresh when
+    the token is within ``leeway_seconds`` of expiry, and forced refresh on
+    401 retries. All token operations are thread-safe.
+
+    The token endpoint is constructed as:
+    ``{keycloak_base}/realms/{realm}/protocol/openid-connect/token``
     """
-    Keycloak client-credentials OAuth2 helper with local, thread-safe token cache.
-    - Fetches token from: {keycloak_base}/realms/{realm}/protocol/openid-connect/token
-    - Auto refreshes when within leeway of expiry
-    - Retries once on 401
-    """
+
     def __init__(
         self,
         creds: ClientCredentials,
@@ -29,6 +40,19 @@ class ClientCredentialsAuth:
         leeway_seconds: int = 30,
         session: Optional[requests.Session] = None,
     ):
+        """Initialize the auth helper.
+
+        Args:
+            creds: Client credentials containing the client ID and secret.
+            keycloak_base: Base URL of the Keycloak server.
+                Defaults to ``"https://id.openquantum.com"``.
+            realm: Keycloak realm name. Defaults to ``"platform"``.
+            scope: Optional OAuth2 scope to request.
+            leeway_seconds: Seconds before token expiry to trigger a
+                proactive refresh. Defaults to 30.
+            session: Optional ``requests.Session`` to use for token requests.
+                A new session is created if not provided.
+        """
         self.keycloak_base = keycloak_base.rstrip("/")
         self.realm = realm
         self.creds = creds
@@ -41,6 +65,7 @@ class ClientCredentialsAuth:
 
     @property
     def token_endpoint(self) -> str:
+        """The full Keycloak token endpoint URL for this realm."""
         return urljoin(
             self.keycloak_base + "/",
             f"realms/{self.realm}/protocol/openid-connect/token",
@@ -72,6 +97,22 @@ class ClientCredentialsAuth:
         self._expires_at = time.time() + int(expires_in)
 
     def get_access_token(self, force: bool = False) -> str:
+        """Return a valid access token, refreshing if needed.
+
+        Uses double-checked locking to ensure only one thread fetches a
+        new token at a time.
+
+        Args:
+            force: If ``True``, forces a token refresh regardless of
+                expiry status. Defaults to ``False``.
+
+        Returns:
+            A valid OAuth2 access token string.
+
+        Raises:
+            RuntimeError: If the Keycloak response is missing an access token.
+            requests.HTTPError: If the token request fails.
+        """
         if force or self._needs_refresh():
             with self._lock:
                 if force or self._needs_refresh():
@@ -79,6 +120,18 @@ class ClientCredentialsAuth:
         return self._access_token  # type: ignore[str-bytes-safe]
 
     def apply_auth_header(self, headers: Dict[str, str]) -> Dict[str, str]:
+        """Add a Bearer authorization header using the current access token.
+
+        Does not mutate the input dict; returns a new dict with the
+        ``Authorization`` header added.
+
+        Args:
+            headers: Existing headers to augment.
+
+        Returns:
+            A new headers dict containing all entries from ``headers`` plus
+            the ``Authorization: Bearer <token>`` header.
+        """
         token = self.get_access_token()
         # don't mutate caller's header dict
         return {**headers, "Authorization": f"Bearer {token}"}