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

{quapp_common-0.0.11.dev6/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.dev6
+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.dev6 → 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.dev6"
+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.dev7/quapp_common/component/backend/job_manager.py

@@ -0,0 +1,302 @@
+#  Quapp Platform Project
+#  job_manager.py
+#  Copyright © CITYNOW Co. Ltd. All rights reserved.
+
+from __future__ import annotations
+
+import atexit
+import threading
+import time
+from datetime import timezone, datetime
+from multiprocessing import Manager, current_process
+from typing import Any, Callable, Dict, Iterable, Optional, Tuple
+
+from ...config.logging_config import logger
+
+SCHEDULER_CALLBACK_URL = 'scheduler_callback_url'
+
+JOB_ID = 'job_id'
+STATUS = 'status'
+UPDATED_AT = 'updated_at'
+META = 'meta'
+
+
+class JobManager:
+    """
+    Cross-process job registry backed by multiprocessing.Manager.
+
+    - Stores job_id -> {"status": <str>, META: <dict>, "updated_at": <float>}
+    - Provides atomic add/update/get operations across processes.
+    - Publishes every change to a cross-process Queue so other processes/threads can react.
+    - Offers:
+        * subscribe(callback): run a background listener thread that invokes `callback(job_id, data)`
+        * watch_updates(timeout=None): generator to pull updates from the queue manually
+    """
+
+    # Process-wide singletons (one per process)
+    _manager: Optional[Manager] = None
+    _jobs: Any = None  # proxy dict
+    _updates_queue: Any = None  # proxy queue
+    _init_lock = threading.Lock()
+    _listener_threads: Dict[str, Tuple[threading.Thread, threading.Event]] = {}
+
+    # --------------- Lifecycle ---------------
+
+    @classmethod
+    def _ensure_initialized(cls) -> None:
+        """
+        Lazily initialize the Manager, shared dict, and update queue.
+        Safe to call multiple times across threads in the same process.
+        """
+        if cls._manager is not None:
+            return
+        with cls._init_lock:
+            if cls._manager is not None:
+                return
+            mgr = Manager()
+            cls._manager = mgr
+            cls._jobs = mgr.dict()  # type: ignore[assignment]
+            cls._updates_queue = mgr.Queue()  # type: ignore[assignment]
+
+            # Ensure a clean shutdown in this process
+            atexit.register(cls._shutdown)
+
+    @classmethod
+    def _shutdown(cls) -> None:
+        """
+        Stop any listener threads in this process and shutdown Manager.
+        """
+        # stop listeners
+        for key, (t, stop_ev) in list(cls._listener_threads.items()):
+            stop_ev.set()
+            # Don't join forever; avoid atexit hang
+            t.join(timeout=1.0)
+            cls._listener_threads.pop(key, None)
+
+        # close manager (safe to call multiple times)
+        if cls._manager is not None:
+            try:
+                cls._manager.shutdown()
+            except Exception as exception:
+                # Manager may already be down if the parent exited
+                logger.exception(f'Error shutting down manager: {exception}')
+                pass
+        cls._manager = None
+        cls._jobs = None
+        cls._updates_queue = None
+
+    # --------------- Core operations ---------------
+
+    @classmethod
+    def add_job(cls, job_id: str, status: str = 'PENDING',
+                meta: Optional[Dict[str, Any]] = None) -> None:
+        """
+        Add a new job. If a job exists, it will be overwritten.
+        Publishes an 'added' event.
+        """
+        cls._ensure_initialized()
+        data = {STATUS    : status, META: meta or {},
+                UPDATED_AT: cls._get_current_utc_time()}
+        cls._jobs[job_id] = data  # proxy is process-safe
+        cls._publish(job_id, {"event": "added", **data})
+
+    @classmethod
+    def update_status(cls, job_id: str, status: str,
+                      meta_update: Optional[Dict[str, Any]] = None) -> None:
+        """
+        Update status (and optionally merge meta) for an existing job.
+        Publishes an 'updated' event.
+        """
+        cls._ensure_initialized()
+        if job_id not in cls._jobs:
+            # Create on the first update to be resilient
+            return cls.add_job(job_id, status=status, meta=meta_update or {})
+
+        current = dict(cls._jobs[job_id])  # materialize proxy value
+        if meta_update:
+            merged_meta = dict(current.get(META) or {})
+            merged_meta.update(meta_update)
+        else:
+            merged_meta = current.get(META) or {}
+
+        if current.get(STATUS) == 'DONE' or current.get(STATUS) == 'FAILED':
+            logger.warning(f'Job {job_id} already completed, ignoring update')
+            return None
+        new_data = {STATUS    : status, META: merged_meta or {},
+                    UPDATED_AT: cls._get_current_utc_time()}
+        cls._jobs[job_id] = new_data
+        cls._publish(job_id, {"event": "updated", **new_data})
+        return None
+
+    @classmethod
+    def remove_job(cls, job_id: str) -> None:
+        """
+        Remove a job if it exists. Publishes a 'removed' event.
+        """
+        cls._ensure_initialized()
+        existed = job_id in cls._jobs
+        if existed:
+            # Capture previous data for potential consumers
+            prev = dict(cls._jobs[job_id])
+            del cls._jobs[job_id]
+            cls._publish(job_id, {"event": "removed", **prev})
+
+    @classmethod
+    def get_status(cls, job_id: str) -> Optional[str]:
+        """
+        Get the current status string for a job, or None if not present.
+        """
+        cls._ensure_initialized()
+        data = cls._jobs.get(job_id)
+        return None if data is None else data.get(STATUS)
+
+    @classmethod
+    def get_job(cls, job_id: str) -> Optional[Dict[str, Any]]:
+        """
+        Get full job data: {"status", META, "updated_at"} or None.
+        """
+        cls._ensure_initialized()
+        data = cls._jobs.get(job_id)
+        return None if data is None else dict(data)
+
+    @classmethod
+    def list_jobs(cls) -> Dict[str, Dict[str, Any]]:
+        """
+        Snapshot of all jobs.
+        """
+        cls._ensure_initialized()
+        # Materialize to plain dict (avoid holding proxies)
+        return {k: dict(v) for k, v in dict(cls._jobs).items()}
+
+    @classmethod
+    def get_scheduler_callback_url(cls, job_id):
+        """
+        Get the scheduler callback URL of a job.
+        """
+        cls._ensure_initialized()
+        data = cls._jobs.get(job_id)
+        return None if data is None else data.get(META).get(
+                SCHEDULER_CALLBACK_URL)
+
+    # --------------- Change publication ---------------
+
+    @classmethod
+    def _publish(cls, job_id: str, payload: Dict[str, Any]) -> None:
+        """
+        Push an update notification to the shared queue.
+        """
+        cls._ensure_initialized()
+        try:
+            cls._updates_queue.put((job_id, payload))
+            logger.debug(f'Published job update: {payload}')
+        except Exception as exception:
+            # If queue is not available (e.g., after shutdown), ignore
+            logger.exception(f'Error publishing job update: {exception}')
+            pass
+
+    @classmethod
+    def watch_updates(cls, timeout: Optional[float] = None) -> Iterable[
+        Tuple[str, Dict[str, Any]]]:
+        """
+        Generator that yields (job_id, payload) for each change.
+        Blocks waiting for new items if the queue is empty.
+        - timeout=None: block indefinitely per item
+        - timeout=float: block up to timeout seconds, yielding nothing if no item
+        """
+        cls._ensure_initialized()
+        q = cls._updates_queue
+        while True:
+            try:
+                item = q.get(
+                        timeout=timeout) if timeout is not None else q.get()
+            except Exception as exception:
+                logger.exception(
+                        f'Queue empty in job update listener: {exception}')
+                # Timeout or queue failure
+                if timeout is not None:
+                    logger.info(f'Watch timeout reached: {timeout}s')
+                    return
+
+                logger.info('Watch terminated')
+                continue
+            yield item
+
+    @classmethod
+    def subscribe(cls, callback: Callable[[str, Dict[str, Any]], None],
+                  name: Optional[str] = None, daemon: bool = True, ) -> str:
+        """
+        Start a background listener thread in the current process that consumes updates
+        and invokes `callback(job_id, payload)`.
+
+        Returns a subscription key that can be used to unsubscribe.
+        """
+        cls._ensure_initialized()
+        proc = current_process().name
+        sub_key = name or f'job_updates_listener@{proc}#{len(cls._listener_threads) + 1}'
+        if sub_key in cls._listener_threads:
+            # Stop existing and replace
+            cls.unsubscribe(sub_key)
+
+        stop_event = threading.Event()
+
+        def _run() -> None:
+            while not stop_event.is_set():
+                try:
+                    job_id, payload = cls._updates_queue.get(timeout=0.2)
+                except Exception as exception:
+                    logger.exception(
+                            f'Queue empty in job update listener {sub_key}: {exception}')
+                    continue
+                try:
+                    callback(job_id, payload)
+                except Exception as exception:
+                    # Keep the listener alive even if callback fails
+                    logger.exception(f'Error in job update callback '
+                                     f'{callback}: {exception}')
+                    pass
+
+        t = threading.Thread(target=_run, name=sub_key, daemon=daemon)
+        t.start()
+        cls._listener_threads[sub_key] = (t, stop_event)
+        return sub_key
+
+    @classmethod
+    def unsubscribe(cls, key: str) -> None:
+        """
+        Stop a previously started subscription listener thread.
+        """
+        pair = cls._listener_threads.get(key)
+        if not pair:
+            return
+        t, stop_event = pair
+        stop_event.set()
+        t.join(timeout=1.0)
+        cls._listener_threads.pop(key, None)
+
+    # --------------- Convenience helpers ---------------
+
+    @classmethod
+    def set_queued(cls, job_id: str,
+                   meta_update: Optional[Dict[str, Any]] = None) -> None:
+        cls.update_status(job_id, 'QUEUED', meta_update)
+
+    @classmethod
+    def set_running(cls, job_id: str,
+                    meta_update: Optional[Dict[str, Any]] = None) -> None:
+        cls.update_status(job_id, 'RUNNING', meta_update)
+
+    @classmethod
+    def set_done(cls, job_id: str,
+                 meta_update: Optional[Dict[str, Any]] = None) -> None:
+        cls.update_status(job_id, 'DONE', meta_update)
+
+    @classmethod
+    def set_failed(cls, job_id: str,
+                   meta_update: Optional[Dict[str, Any]] = None) -> None:
+        cls.update_status(job_id, 'FAILED', meta_update)
+
+    @classmethod
+    def _get_current_utc_time(cls) -> str:
+        now = time.time()
+        return datetime.fromtimestamp(now, tz=timezone.utc).isoformat().replace(
+                '+00:00', 'Z')

quapp_common-0.0.11.dev7/quapp_common/component/callback/update_job_metadata.py

@@ -0,0 +1,77 @@
+#  Quapp Platform Project
+#  update_job_metadata.py
+#  Copyright © CITYNOW Co. Ltd. All rights reserved.
+
+import requests
+
+from ..backend.job_manager import JobManager
+from ...config.logging_config import job_logger
+from ...data.response.job_response import JobResponse
+from ...util.http_utils import create_application_json_header, \
+    get_job_id_from_url
+from ...util.response_utils import generate_response
+
+
+def update_job_metadata(job_response: JobResponse, callback_url: str):
+    # Helpers to improve readability and remove duplication
+    def _log_http_result(tag: str, resp):
+        logger.info(
+                f"Request to {tag} completed with status code: {resp.status_code}")
+        if not resp.ok:
+            logger.warning(
+                    f"Unexpected status code received from {tag}: {resp.status_code}, response content: {resp.content}")
+
+    def _update_local_status() -> None:
+        """
+                Update local JobManager status based on callback URL semantics:
+                - contains 'FAILED' => FAILED
+                - contains 'FINALIZATION_PASSED' => DONE
+                - otherwise => RUNNING
+                """
+        url_upper = (callback_url or "").upper()
+        if "FAILED" in url_upper:
+            JobManager.set_failed(job_id=job_id)
+        elif "FINALIZATION_PASSED" in url_upper:
+            JobManager.set_done(job_id=job_id)
+        else:
+            JobManager.set_running(job_id=job_id)
+
+    def _patch_scheduler() -> None:
+        job_details = JobManager.get_job(job_id)
+        scheduler_callback_url = job_details.get('meta').get(
+                'scheduler_callback_url')
+        scheduler_payload = {'job_id'    : job_id,
+                             'status'    : job_details.get('status'),
+                             'updated_at': job_details.get('updated_at')}
+        scheduler_response = requests.patch(url=scheduler_callback_url,
+                                            json=scheduler_payload)
+        _log_http_result('scheduler', scheduler_response)
+
+    job_id = get_job_id_from_url(callback_url)
+    logger = job_logger(job_id)
+    logger.info(
+            f'Calling backend to update job metadata at URL: {callback_url}')
+
+    request_body = generate_response(job_response)
+
+    try:
+        # Update local job status and notify scheduler
+        _update_local_status()
+        _patch_scheduler()
+
+        request_headers = create_application_json_header(
+                token=job_response.user_token,
+                project_header=job_response.project_header,
+                workspace_header=job_response.workspace_header)
+
+        response = requests.patch(url=callback_url, json={'data': request_body},
+                                  headers=request_headers)
+
+        # Log backend response
+        _log_http_result('backend', response)
+
+    except Exception as exception:
+        logger.exception(f'Error occurred while calling backend: {exception}',
+                         exc_info=True)
+
+        raise exception

{quapp_common-0.0.11.dev6 → quapp_common-0.0.11.dev7}/quapp_common/data/request/request.py

@@ -4,6 +4,7 @@
 
 from ..response.authentication import Authentication
 from ..response.custom_header import CustomHeader
+from ...component.backend.job_manager import JobManager
 from ...config.logging_config import job_logger
 from ...data.callback.callback_url import CallbackUrl
 from ...util.http_utils import get_custom_header
@@ -26,6 +27,7 @@ class Request:
         self.workspace_header: CustomHeader = get_custom_header(request_data,
                                                                 'workspaceHeader')
         self.logger = job_logger(self.job_id)
+        JobManager.add_job(job_id=self.job_id, status='RUNNING', meta={
+            'scheduler_callback_url': request_data.get('schedulerCallBackURL')})
         self.logger.info(
-                f"Initializing Request with job id: {self.job_id} and provider job id: {self.provider_job_id}"
-        )
+                f"Initializing Request with job id: {self.job_id} and provider job id: {self.provider_job_id}")

quapp_common-0.0.11.dev7/quapp_common/model/invocation.py

@@ -0,0 +1,54 @@
+#  Quapp Platform Project
+#  invocation.py
+#  Copyright © CITYNOW Co. Ltd. All rights reserved.
+import logging
+import traceback as tb
+from dataclasses import dataclass
+from datetime import datetime
+
+
+class Event:
+    logger = logging.getLogger("model.Invocation.Event")
+    logger.setLevel(logging.DEBUG)
+
+    def __init__(self, request):
+        self.request_body = {}
+        self.request = request
+
+    def json(self):
+        return self.request_body
+
+
+@dataclass
+class Result:
+    def __init__(self):
+        self.timestamp: datetime = datetime.now()
+
+    def serialize(self):
+        return {
+            'timestamp': self.timestamp.isoformat()
+        }
+
+
+@dataclass
+class Success(Result):
+    def __init__(self, data):
+        super().__init__()
+        self.data = data
+
+    def serialize(self):
+        serialize = super().serialize()
+        serialize['data'] = self.data
+        return serialize
+
+
+@dataclass
+class Error(Result):
+    def __init__(self, error: Exception):
+        super().__init__()
+        self.error = tb.format_exception(error)
+
+    def serialize(self):
+        serialize = super().serialize()
+        serialize['error'] = self.error
+        return serialize

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: quapp-common
-Version: 0.0.11.dev6
+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.dev6 → quapp_common-0.0.11.dev7}/quapp_common.egg-info/SOURCES.txt

@@ -8,6 +8,7 @@ quapp_common.egg-info/dependency_links.txt
 quapp_common.egg-info/requires.txt
 quapp_common.egg-info/top_level.txt
 quapp_common/async_tasks/__init__.py
+quapp_common/async_tasks/async_invocation_task.py
 quapp_common/async_tasks/async_task.py
 quapp_common/async_tasks/export_circuit_task.py
 quapp_common/async_tasks/post_processing_task.py
@@ -16,6 +17,7 @@ quapp_common/component/backend/__init__.py
 quapp_common/component/backend/invocation.py
 quapp_common/component/backend/job_fetcher.py
 quapp_common/component/backend/job_fetching.py
+quapp_common/component/backend/job_manager.py
 quapp_common/component/callback/__init__.py
 quapp_common/component/callback/update_job_metadata.py
 quapp_common/component/device/__init__.py
@@ -64,6 +66,7 @@ quapp_common/factory/provider_factory.py
 quapp_common/handler/__init__.py
 quapp_common/handler/handler.py
 quapp_common/model/__init__.py
+quapp_common/model/invocation.py
 quapp_common/model/device/__init__.py
 quapp_common/model/device/custom_device.py
 quapp_common/model/device/device.py

{quapp_common-0.0.11.dev6 → quapp_common-0.0.11.dev7}/quapp_common.egg-info/requires.txt

@@ -3,6 +3,7 @@ requests
 numpy
 matplotlib
 pylatexenc
+starlette
 
 [dev]
 black

quapp_common-0.0.11.dev6/README.md

@@ -1,57 +0,0 @@
-# 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 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.
-
-## 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.
-
-## Installation
-
-Install via pip:
-
-```bash
-pip install quapp-common
-```
-
-## 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.
-
----
-
-For detailed usage and API references, please refer to the in-code documentation
-or contact the maintainers.
- 

quapp_common-0.0.11.dev6/quapp_common/component/callback/update_job_metadata.py

@@ -1,41 +0,0 @@
-#  Quapp Platform Project
-#  update_job_metadata.py
-#  Copyright © CITYNOW Co. Ltd. All rights reserved.
-
-import requests
-
-from ...config.logging_config import job_logger
-from ...data.response.job_response import JobResponse
-from ...util.http_utils import create_application_json_header, \
-    get_job_id_from_url
-from ...util.response_utils import generate_response
-
-
-def update_job_metadata(job_response: JobResponse, callback_url: str):
-    logger = job_logger(get_job_id_from_url(callback_url))
-    logger.info(
-            f"Calling backend to update job metadata at URL: {callback_url}")
-
-    request_body = generate_response(job_response)
-
-    try:
-        request_headers = create_application_json_header(
-                token=job_response.user_token,
-                project_header=job_response.project_header,
-                workspace_header=job_response.workspace_header)
-
-        response = requests.patch(url=callback_url, json={'data': request_body},
-                                  headers=request_headers)
-
-        logger.info(
-                f"Request to backend completed with status code: {response.status_code}")
-        if not response.ok:
-            logger.warning(
-                    f"Unexpected status code received: {response.status_code}, response content: {response.content}")
-
-
-    except Exception as exception:
-        logger.exception(f"Error occurred while calling backend: {exception}",
-                     exc_info=True)
-
-        raise exception