quapp-common 0.0.11.dev5__tar.gz → 0.0.11.dev7__tar.gz

{quapp_common-0.0.11.dev5/quapp_common.egg-info → quapp_common-0.0.11.dev7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: quapp-common
-Version: 0.0.11.dev5
+Version: 0.0.11.dev7
 Summary: Quapp common library supporting Quapp Platform for Quantum Computing
 Author-email: "CITYNOW Co. Ltd. " <corp@citynow.vn>
 License: The MIT License (MIT)
@@ -24,6 +24,7 @@ Requires-Dist: requests
 Requires-Dist: numpy
 Requires-Dist: matplotlib
 Requires-Dist: pylatexenc
+Requires-Dist: starlette
 Provides-Extra: dev
 Requires-Dist: black; extra == "dev"
 Requires-Dist: bumpver; extra == "dev"
@@ -42,12 +43,11 @@ Quapp common library supporting Quapp Platform for Quantum Computing.
 Quantum Computing by providing common utilities, configurations, and
 abstractions for working with
 quantum providers and devices.
-
-Recent improvements focus on cleaner and more consistent logging, enhanced error
-handling, and
-standardizing header management by adding workspace-specific headers instead of
-tenant-specific ones,
-improving maintainability and clarity.
+Recent improvements add first-class asynchronous job processing with a
+cross-process JobManager,
+background task execution, and standardized result models for immediate client
+responses while work
+continues in the background.
 
 ## Features
 
@@ -61,6 +61,17 @@ improving maintainability and clarity.
 - Enhanced error handling and job metadata update mechanisms.
 - Simplified and cleaner HTTP request/response logging and URL parsing
   utilities.
+- Asynchronous job processing:
+    - AsyncInvocationTask to run handlers in a background thread pool and return
+      immediate responses.
+    - JobManager for cross-process job registry with atomic add/update/get and
+      pub-sub updates.
+    - Standard Event/Result (Success, Error) models for consistent async
+      responses.
+    - Scheduler integration via callback URL; local updates are patched to the
+      scheduler.
+    - Safety: updates to jobs already DONE/FAILED are ignored to prevent
+      post-completion mutations.
 
 ## Installation
 
@@ -70,22 +81,27 @@ Install via pip:
 pip install quapp-common
 ```
 
+Notes:
+
+- From version 0.0.11.dev7, `starlette` is a direct dependency to support
+  background execution helpers.
+
 ## Recently Changes Highlights
 
-- Added workspace-specific classes for request, response, and promise,
-  consolidating code to unify context handling.
-- Refactored logging throughout the codebase, removing redundant debug logs and
-  adding context-rich log messages.
-- Improved URL parsing and job ID extraction, especially in HTTP utilities, to
-  better track jobs.
-- Cleaned up logging configuration files to standardize log formats and levels.
-- Added robust error handling in job execution and analysis pipelines, ensuring
-  detailed failure reporting.
-- Simplified header and request body logging, improving performance and
-  readability.
+- Version bump to 0.0.11.dev7 and dependency update (add `starlette`).
+- Introduce asynchronous job processing primitives:
+    - AsyncInvocationTask for background execution with immediate client
+      response.
+    - Event and standardized Result models (Success, Error).
+- Introduce JobManager for cross-process job management and update publication.
+- Integrate JobManager into Request to register jobs and carry scheduler
+  callback URL.
+- Modularize update_job_metadata with clearer helpers; patch scheduler on local
+  state changes.
+- Fix: ignore updates for jobs that are already DONE or FAILED.
+- Improve logging and error handling (use full tracebacks, cleaner logs).
 
 ---
 
 For detailed usage and API references, please refer to the in-code documentation
 or contact the maintainers.
- 

quapp_common-0.0.11.dev7/README.md

@@ -0,0 +1,72 @@
+# quapp-common
+
+Quapp common library supporting Quapp Platform for Quantum Computing.
+
+## Overview
+
+`quapp-common` is a Python library designed to support the Quapp Platform for
+Quantum Computing by providing common utilities, configurations, and
+abstractions for working with
+quantum providers and devices.
+Recent improvements add first-class asynchronous job processing with a
+cross-process JobManager,
+background task execution, and standardized result models for immediate client
+responses while work
+continues in the background.
+
+## Features
+
+- Provider and device factory for quantum computing platforms.
+- Logging and configuration utilities with improved and detailed log messages.
+- Support for AWS Braket, OQC Cloud, Qiskit, PennyLane, DWave Ocean, and Quapp
+  quantum simulators.
+- Refactored classes and utilities to remove tenant-specific request, response,
+  and promise classes.
+- Standardized naming by renaming `ProjectHeader` to `CustomHeader`.
+- Enhanced error handling and job metadata update mechanisms.
+- Simplified and cleaner HTTP request/response logging and URL parsing
+  utilities.
+- Asynchronous job processing:
+    - AsyncInvocationTask to run handlers in a background thread pool and return
+      immediate responses.
+    - JobManager for cross-process job registry with atomic add/update/get and
+      pub-sub updates.
+    - Standard Event/Result (Success, Error) models for consistent async
+      responses.
+    - Scheduler integration via callback URL; local updates are patched to the
+      scheduler.
+    - Safety: updates to jobs already DONE/FAILED are ignored to prevent
+      post-completion mutations.
+
+## Installation
+
+Install via pip:
+
+```bash
+pip install quapp-common
+```
+
+Notes:
+
+- From version 0.0.11.dev7, `starlette` is a direct dependency to support
+  background execution helpers.
+
+## Recently Changes Highlights
+
+- Version bump to 0.0.11.dev7 and dependency update (add `starlette`).
+- Introduce asynchronous job processing primitives:
+    - AsyncInvocationTask for background execution with immediate client
+      response.
+    - Event and standardized Result models (Success, Error).
+- Introduce JobManager for cross-process job management and update publication.
+- Integrate JobManager into Request to register jobs and carry scheduler
+  callback URL.
+- Modularize update_job_metadata with clearer helpers; patch scheduler on local
+  state changes.
+- Fix: ignore updates for jobs that are already DONE or FAILED.
+- Improve logging and error handling (use full tracebacks, cleaner logs).
+
+---
+
+For detailed usage and API references, please refer to the in-code documentation
+or contact the maintainers.

{quapp_common-0.0.11.dev5 → quapp_common-0.0.11.dev7}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "quapp-common"
-version = "0.0.11.dev5"
+version = "0.0.11.dev7"
 description = "Quapp common library supporting Quapp Platform for Quantum Computing"
 readme = "README.md"
 authors = [{ name = "CITYNOW Co. Ltd. ", email = "corp@citynow.vn" }]
@@ -20,7 +20,8 @@ dependencies = [
     "requests",
     "numpy",
     "matplotlib",
-    "pylatexenc"
+    "pylatexenc",
+    "starlette"
 ]
 requires-python = ">=3.7"
 

quapp_common-0.0.11.dev7/quapp_common/async_tasks/async_invocation_task.py

@@ -0,0 +1,80 @@
+#  Quapp Platform Project
+#  async_invocation_task.py
+#  Copyright © CITYNOW Co. Ltd. All rights reserved.
+import asyncio
+import sys
+
+from starlette.concurrency import run_in_threadpool
+from starlette.responses import JSONResponse
+
+from ..async_tasks.async_task import AsyncTask
+from ..component.backend.job_manager import JobManager
+from ..config.logging_config import logger
+from ..factory.handler_factory import HandlerFactory
+from ..model.invocation import Event, Error, Success
+
+
+class AsyncInvocationTask(AsyncTask):
+    """
+    Handles asynchronous invocation tasks, designed to process events with
+    specific handlers and generate immediate responses.
+
+    The class is aimed at enabling tasks to be processed asynchronously, involving
+    a handler factory and functions for event processing and post-processing. It
+    executes operations in a background thread pool to ensure quick response to
+    clients, allowing them to poll for job status updates. Its primary purpose is
+    to facilitate efficient asynchronous processing of jobs without blocking the
+    main application flow.
+
+    Attributes:
+        handler_factory: Factory instance that produces job handlers.
+        event: Event to be processed by the created handler.
+        processing_fn: Function to be executed during the job processing stage.
+        post_processing_fn: Function to be executed post-job processing.
+    """
+
+    def __init__(self, handler_factory: HandlerFactory, event: Event,
+                 processing_fn, post_processing_fn):
+        super().__init__()
+        self.handler_factory = handler_factory
+        self.event = event
+        self.processing_fn = processing_fn
+        self.post_processing_fn = post_processing_fn
+
+    def do(self) -> JSONResponse:
+        """
+        Handles executing a job asynchronously and provides an immediate response with the job's ID and
+        status. Logging is configured dynamically based on the provided job ID.
+
+        Returns:
+            JSONResponse: A response object with the status and job ID if the job submission succeeds,
+            or an error message if there is an issue.
+
+        Raises:
+            Exception: If any error occurs during job processing, it is logged, and an appropriate error
+            response is returned.
+        """
+        try:
+            job_id = self.event.json().get('jobId')
+            if job_id is None:
+                raise Exception("Job ID is missing from event")
+            logger.add(sink=sys.stderr,
+                       format="[ConsoleJobLog][" + job_id + "] " + "{level} : {time} : {message}: {process}",
+                       level='DEBUG')
+
+            # Define the blocking work
+            def _run_handle():
+                return self.handler_factory.create_handler(self.event,
+                                                           self.processing_fn,
+                                                           self.post_processing_fn).handle()
+
+            # Run in the background threadpool so this request can return immediately
+            asyncio.create_task(run_in_threadpool(_run_handle))
+
+            # Respond immediately so clients can poll GET /jobs/{job_id}
+            return JSONResponse(status_code=200, content=Success(
+                    JobManager.get_job(job_id)).serialize())
+        except Exception as exception:
+            logger.exception(f"An error occurred: {exception}")
+            return JSONResponse(status_code=400,
+                                content=Error(exception).serialize())

{quapp_common-0.0.11.dev5 → quapp_common-0.0.11.dev7}/quapp_common/async_tasks/export_circuit_task.py

@@ -11,6 +11,7 @@ from .async_task import AsyncTask
 from ..config.logging_config import job_logger
 from ..data.async_task.circuit_export.backend_holder import BackendDataHolder
 from ..data.async_task.circuit_export.circuit_holder import CircuitDataHolder
+from ..data.response.custom_header import CustomHeader
 from ..enum.media_type import MediaType
 from ..util.file_utils import FileUtils
 from ..util.http_utils import create_bearer_header, get_job_id_from_url
@@ -20,8 +21,11 @@ class CircuitExportTask(AsyncTask):
     MAX_CIRCUIT_IMAGE_SIZE = 5 * (1024 ** 2)
 
     def __init__(self, circuit_data_holder: CircuitDataHolder,
-                 backend_data_holder: BackendDataHolder):
+                 backend_data_holder: BackendDataHolder,
+                 project_header: CustomHeader, workspace_header: CustomHeader):
         super().__init__()
+        self.project_header = project_header
+        self.workspace_header = workspace_header
         self.circuit_data_holder = circuit_data_holder
         self.backend_data_holder = backend_data_holder
         self.logger = job_logger(
@@ -43,8 +47,8 @@ class CircuitExportTask(AsyncTask):
             self.logger.debug('Converting circuit to SVG')
             figure_buffer = self.__convert()
         except Exception as e:
-            self.logger.error(f"Error converting circuit to SVG: {e}",
-                              exc_info=True)
+            self.logger.exception(f"Error converting circuit to SVG: {e}",
+                                  exc_info=True)
             return
 
         try:
@@ -54,7 +58,7 @@ class CircuitExportTask(AsyncTask):
             self.logger.debug(f"Content type: {content_type}")
             self.logger.debug(f"Buffer size: {len(io_buffer_value)} bytes")
         except Exception as e:
-            self.logger.error(
+            self.logger.exception(
                     f"Error determining if circuit SVG should be zipped: {e}",
                     exc_info=True)
             return
@@ -64,11 +68,12 @@ class CircuitExportTask(AsyncTask):
             self.__send(io_buffer_value=io_buffer_value,
                         content_type=content_type)
             self.logger.debug("Circuit sent to backend successfully.")
+            return
         except Exception as e:
-            self.logger.error(f"Error sending exported circuit to backend: {e}",
-                              exc_info=True)
-
-        self.logger.info("Circuit export task finished.")
+            self.logger.exception(
+                    f"Error sending exported circuit to backend: {e}",
+                    exc_info=True)
+            return
 
     def __convert(self):
         """
@@ -81,8 +86,8 @@ class CircuitExportTask(AsyncTask):
         try:
             circuit_figure = transpiled_circuit.draw(output='mpl', fold=-1)
         except Exception as exception:
-            self.logger.error(f"Error drawing circuit: {exception}",
-                              exc_info=True)
+            self.logger.exception(f"Error drawing circuit: {exception}",
+                                  exc_info=True)
             raise exception
 
         self.logger.debug("Converting circuit figure to SVG file...")
@@ -93,7 +98,7 @@ class CircuitExportTask(AsyncTask):
             self.logger.debug(
                     f"SVG export complete. Size: {figure_buffer.getbuffer().nbytes} bytes")
         except Exception as exception:
-            self.logger.error(
+            self.logger.exception(
                     f"Error saving circuit figure to SVG: {exception}",
                     exc_info=True)
             raise exception
@@ -135,16 +140,17 @@ class CircuitExportTask(AsyncTask):
 
         try:
             response = requests.post(url=url, headers=create_bearer_header(
-                    self.backend_data_holder.user_token), files=payload)
+                    self.backend_data_holder.user_token, self.project_header,
+                    self.workspace_header), files=payload)
         except Exception as exception:
-            self.logger.error(f"HTTP request failed: {exception}",
-                              exc_info=True)
+            self.logger.exception(f"HTTP request failed: {exception}",
+                                  exc_info=True)
             raise
 
         if response.ok:
             self.logger.info("Request sent to QuaO backend successfully.")
         else:
-            self.logger.error(
+            self.logger.exception(
                     f"Sending request to QuaO backend failed with status {response.status_code}! Response: {response.content}")
 
         self.logger.debug("HTTP request complete.")

{quapp_common-0.0.11.dev5 → quapp_common-0.0.11.dev7}/quapp_common/component/backend/invocation.py

@@ -77,9 +77,9 @@ class Invocation(ABC):
         circuit = self.__prepare_circuit(circuit_preparation_fn)
 
         if circuit is None:
-            self.logger.error(
+            self.logger.exception(
                     "Circuit preparation failed, returning None from pre-execute")
-            return None
+            raise ValueError("Circuit preparation failed")
 
         try:
             self.logger.debug("Preparing backend data")
@@ -88,12 +88,13 @@ class Invocation(ABC):
                     f"Backend data prepared: device {self.backend_information.device_name}, provider {self.backend_information.provider_tag.value}")
 
         except Exception as exception:
-            self.logger.error(f"Error when prepare backend data: {exception}",
-                              exc_info=True)
+            self.logger.exception(
+                f"Error when prepare backend data: {exception}",
+                exc_info=True)
 
             job_response = build_error_job_response(exception,
                                                     message='Error when prepare backend data')
-
+            job_response.authentication = self.authentication
             update_job_metadata(job_response, self.callback_dict.get(
                     InvocationStep.PREPARATION).on_error)
 
@@ -113,7 +114,7 @@ class Invocation(ABC):
 
         try:
             if self.backend_information is None:
-                self.logger.error(
+                self.logger.exception(
                         "Backend information is None before execution")
                 raise ValueError("Backend is not found")
 
@@ -129,7 +130,7 @@ class Invocation(ABC):
             device = self._create_device(provider)
 
         except Exception as exception:
-            self.logger.error(
+            self.logger.exception(
                     f"Exception when create provider or device: {exception}",
                     exc_info=True)
 
@@ -182,8 +183,8 @@ class Invocation(ABC):
             return circuit
 
         except Exception as exception:
-            self.logger.error(f'Error when prepare circuit: {exception}',
-                              exc_info=True)
+            self.logger.exception(f'Error when prepare circuit: {exception}',
+                                  exc_info=True)
 
             job_response = build_error_job_response(exception, job_response,
                                                     message='Error when prepare circuit')

{quapp_common-0.0.11.dev5 → quapp_common-0.0.11.dev7}/quapp_common/component/backend/job_fetcher.py

@@ -116,7 +116,7 @@ class JobFetcher(ABC):
                 update_job_metadata(job_response, self.callback_urls[
                     InvocationStep.EXECUTION].on_done)
             elif job_status == JobStatus.ERROR.value:
-                self.logger.error("Job resulted in error, handling failure")
+                self.logger.exception("Job resulted in error, handling failure")
 
                 self._handle_failed_job(original_job_result, job_response)
                 update_job_metadata(job_response, self.callback_urls[
@@ -127,7 +127,7 @@ class JobFetcher(ABC):
                 job_response.status_code = StatusCode.POLLING
 
         except Exception as exception:
-            self.logger.error(
+            self.logger.exception(
                     f"Exception during job fetch for provider_job_id {self.provider_job_id}: {exception}",
                     exc_info=True)
 
@@ -151,7 +151,7 @@ class JobFetcher(ABC):
     def _handle_failed_job(self, original_job_result,
                            job_response: JobResponse):
         """Handles the job result when the job has encountered an error."""
-        self.logger.error("Parsing job result from failed job")
+        self.logger.exception("Parsing job result from failed job")
         job_response.job_result = parse(original_job_result)
 
     def _process_job_result(self, original_job_result,
@@ -205,7 +205,7 @@ class JobFetcher(ABC):
             return job_response
 
         except Exception as exception:
-            self.logger.error(f"Exception during analysis: {exception}",
+            self.logger.exception(f"Exception during analysis: {exception}",
                               exc_info=True)
             from ...util.response_utils import build_error_job_response
             job_response = build_error_job_response(exception, job_response,

{quapp_common-0.0.11.dev5 → quapp_common-0.0.11.dev7}/quapp_common/component/backend/job_fetching.py

@@ -75,7 +75,7 @@ class JobFetching(ABC):
                         InvocationStep.EXECUTION).on_done)
 
             elif JobStatus.ERROR.value.__eq__(job_response.job_status):
-                self.logger.error("Job resulted in error, handling failure")
+                self.logger.exception("Job resulted in error, handling failure")
 
                 job_response.job_result = parse(original_job_result)
 
@@ -152,7 +152,7 @@ class JobFetching(ABC):
             return job_response
 
         except Exception as exception:
-            self.logger.error(
+            self.logger.exception(
                     "Exception when analyst job result with provider_job_id {0}: {1}".format(
                             self.provider_job_id, str(exception)))