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.
• Multi-language SDK support:
  • Language enum for validating and resolving Python, JavaScript, and Q# runtimes.
  • Standalone dispatch() function (formerly SubprocessDispatcher class) to delegate tasks to non-Python runtimes via subprocess with timeout management and JSON payload processing; supports Node.js and precompiled Q# binary (./handler_runner_bin/Function[.exe]) runners.
  • Working directory configurable via QUAPP_WORKING_DIR environment variable; falls back to os.getcwd() when unset.
  • SubprocessBridge class integrating standalone dispatcher, circuit adapter, and result serializer for seamless JS/Q#-Python handler interaction.
  • Standalone adapt() function (formerly CircuitAdapter class) for converting subprocess circuit outputs into native SDK formats (OpenQASM, QUBO, JSON) across Qiskit, Braket, PennyLane, PyQuil, Qibo, Qulacs, and CUDA Quantum.
  • Standalone serialize() function (formerly ResultSerializer class) for converting complex job results into JSON-serializable dictionaries for subprocess communication.

Installation

Install via pip:

pip install quapp-common

Notes:

• From version 0.0.11.dev7, starlette is a direct dependency to support background execution helpers.
• From version 0.0.12.dev1, qibo and dimod are added as dependencies to support Qibo and D-Wave Ocean SDK integrations.

Recently Changes Highlights

v0.0.14.dev1 — Error logging & observability (Phase 0)

Mục tiêu: Function Log và Job Log phải chỉ ra được nguyên nhân lỗi. Toàn bộ thay đổi trong bản này là additive hoặc bug fix — không đổi contract callback, không đổi schema job_result, không cần frontend/backend sửa gì.

Logging (config/)

• Thêm config/log_context.py: bind_job() / enrich_job_context() đặt job_id, trace_id, sdk, provider, device vào contextvars. Mọi log sau đó tự có đủ field, kể cả log của Provider / DeviceSelection / *Factory — những chỗ trước đây rơi vào context "QuappLibs" nên không gắn được vào job nào.
• configure_logging() idempotent. Trước đây AsyncInvocationTask.do() gọi logger.add(sink=sys.stderr, ...) cho mỗi request, nên sau N job có N+1 sink và mỗi dòng log in N+1 lần.
• Thêm InterceptHandler + install_stdlib_intercept(): đẩy mọi record của stdlib logging sang loguru. Cần thiết vì 24/34 template trong quapp-sdk-templates dùng logging.getLogger('index') mà không cấu hình handler — debug/info của chúng bị drop im lặng và exception in ra không có prefix [ConsoleJobLog] lẫn job_id. Log của uvicorn/qiskit/botocore cũng về cùng một format.
• Thêm JSON sink cho structured logging, bật bằng QUAPP_LOG_FORMAT=json|both (default text, giữ nguyên hành vi cũ). Field: jobId, traceId, phase, category, errorCode, sdk, provider, device, event, durationMs.
• Thêm redaction filter: mask token / apiKey / authentication / clientSecret / … trước khi ghi log, áp dụng cả cho stack trace.
• Fix: text formatter thiếu {exception}. Với formatter dạng callable, loguru không tự append traceback — nên trước đây mọi logger.exception() trong codebase không in ra stack trace nào.
• Fix: depth trong intercept khiến mọi record hiện là logging:callHandlers:<line> thay vì file:line của nơi gọi log.
• Fix: với enqueue=True, traceback object không picklable nên bị thay bằng None sau khi qua queue. Traceback nay được format sẵn ở filter.

Error từ runner không phải Python (component/dispatcher.py, bridge.py)

• Bỏ subprocess.run(..., check=True). Nó raise CalledProcessError trước khi đọc được output, làm nhánh _extract_error_message() thành dead code và user chỉ thấy Command '[...]' returned non-zero exit status 1.
• Thêm HandlerRuntimeError mang language, action, error_type, stack (stack của runtime gốc — JS/.NET), exit_code, signal_name. Sáu tình huống được phân biệt: runner không có trong image, timeout, bị signal (handler.c segfault → returncode âm, stdout rỗng), structured error trên stdout, exit code khác 0, và output không phải JSON hợp lệ.
• Đọc được cả contract cũ (error dạng string, stack trên stderr) nên không cần deploy đồng thời với template.
• _format_exception() đưa handlerStackTrace / language / action / exitCode / signal lên job_result cho lỗi handler JS/Q#/C.

Đường lỗi (model/device/device.py, util/response_utils.py, …)

• Device._on_execution dùng build_error_job_response() thay cho job_result = {"error": str(exception)} và log ở ERROR thay vì DEBUG. Đây là đường lỗi quan trọng nhất (submit circuit lên device) và trước đây là đường mất thông tin nhiều nhất.
• build_error_job_response() nay tự phát một log ERROR duy nhất cho mọi lỗi, nên Job Log và Function Log không còn lệch nhau.
• Truyền stage cho 8 call-site còn thiếu (trước đây 10/13 call-site rơi vào default 'while running your job').
• Fix generate_response(): nhánh else truy cập job_response.status_code khi job_response là falsy → AttributeError, thay lỗi gốc bằng lỗi khác.
• Fix job_fetching.py: __produce_histogram_data / __get_execution_time khai báo @staticmethod nhưng dùng self.logger → NameError khi được gọi.
• DeviceSelection: không log nguyên response (chứa token provider) và không nhét response.content thô vào exception (nội dung này chảy vào job_result rồi hiện lên UI).
• PostProcessingTask: bỏ print() ghi thẳng ra stdout (không qua sink nên không được redact và không có job_id).

Test

• tests/test_logging_config.py — redaction, idempotent sink, job context, intercept stdlib, exception payload.
• tests/test_dispatcher_runner_error.py — 6 nhánh phân loại lỗi runner.

v0.0.13.dev2

• Fix: _openqasm_to_braket in circuit_adapter.py now injects a default Probability result type when the Braket circuit produced by tk_to_braket has no result types. OpenQASM circuits submitted from non-Python runtimes (e.g. Q#) do not carry explicit measurement annotations, so the converted Braket circuit would have an empty result_types list and fail at execution time. The fix adds circuit.probability(target=list(range(circuit.qubit_count))) before returning, ensuring every Braket job has at least one result type.

v0.0.13.dev1

• Refactor: Replace class-based subprocess components with standalone module-level functions for simpler imports and testability:
  • SubprocessDispatcher class → dispatch() and is_subprocess_language() in dispatcher.py.
  • CircuitAdapter class → adapt() and private helper functions in circuit_adapter.py.
  • ResultSerializer class → serialize() in result_serializer.py.
  • SubprocessBridge retains its class form but delegates internally to the new standalone functions.
• Refactor dispatcher.py: WORKING_DIR is now read from the QUAPP_WORKING_DIR environment variable (previously hardcoded None); falls back to os.getcwd() when the variable is unset.
• Refactor dispatcher.py: Q# runner command changed from dotnet run --project HandlerRunner.csproj to a precompiled platform-specific binary — ./handler_runner_bin/Function.exe on Windows and ./handler_runner_bin/Function on other platforms — eliminating the dotnet toolchain requirement at runtime.
• Refactor circuit_adapter.py: Extract _load_qasm_circuit(qasm_str) private utility that centralises OpenQASM 2.0 string parsing with Qiskit version compatibility — uses qiskit.qasm2.loads (Qiskit >= 1.0) and falls back to QiskitCircuit.from_qasm_str (Qiskit < 1.0).
• Fix: subprocess.run now passes check=True so a non-zero exit code raises CalledProcessError before the manual return-code branch is reached.
• Add unit tests: tests/test_circuit_adapter.py, tests/test_json_parser_utils.py, tests/test_result_serializer.py.

v0.0.12.dev15

• Extend multi-language SDK support with Q# (QSharp) runtime:
  • Add QSHARP to Language enum.
  • Add Q# runner configuration to SubprocessDispatcher (dotnet run --project ., 300 s timeout).

v0.0.12.dev14

• Fix: CircuitAdapter._adapt_openqasm for Sdk.PENNYLANE now catches the "Failed to load the qasm plugin" error raised by qml.from_qasm on PennyLane versions that route QASM parsing through the IO plugin registry and require pennylane-qiskit to be installed (affects both older releases and the current latest). When the error is detected, it falls back to parsing the QASM string via Qiskit (a hard dependency) and emitting native PennyLane operations gate-by-gate through the new CircuitAdapter._qiskit_to_pennylane helper. Supported gates: H, X, Y, Z, S, Sdg (→ PhaseShift −π/2), T, Tdg (→ PhaseShift −π/4), CX, CZ, SWAP, RX, RY, RZ, P/U1 (→ PhaseShift), U2, U3/U; unrecognized gates are logged as a warning and skipped.

v0.0.12.dev13

• Fix: CircuitAdapter._adapt_openqasm for Sdk.PENNYLANE now injects string sentinels ("Expectation", "Variance", "Sample", "Probability", "State", "MidMeasure") back into pennylane.measurements when they are absent. PennyLane 0.37 removed ObservableReturnTypes from that module, but legacy plugins such as pennylane-rigetti import these names at module level and crash with ImportError before the device is created. The shim is injected inside __pre_execute, before PennylaneInvocation creates the device, so the plugin import succeeds and the removed code paths are bypassed at runtime.

v0.0.12.dev12

• Feat: add QUAPP_HPC to ProviderTag enum to support the Slurm HPC integration. Required by quapp-hpc so its SlurmProvider can register itself in the shared ProviderTag namespace; without this, importing quapp-hpc fails at SlurmProvider.__init__ with AttributeError on the enum lookup.

v0.0.12.dev11

• Enhance: CircuitAdapter now emits structured debug logs at each routing decision — SDK selected, QASM string length, qubit count, per-SDK adapter chosen, tk_to_braket return type (tuple vs bare Circuit), DenseMatrix fallback for unrecognized/parametric gates in _qiskit_to_qulacs, and QUBO entry counts before and after parsing.
• Enhance: SubprocessBridge now emits debug logs on initialisation (language, sdk), processing() (input keys, JS status, adapted circuit type), and post_processing() (job-result type, serialised keys, JS status, result type); subprocess failures are additionally promoted to logger.error before the RuntimeError is raised.

v0.0.12.dev10

• Fix: CircuitAdapter._adapt_openqasm for Sdk.BRAKET now handles the breaking API change in pytket-braket >= 0.35, where tk_to_braket returns a (Circuit, n_shots) tuple instead of a bare Circuit — the method unpacks the first element when a tuple is returned and passes through the value unchanged for older versions.

v0.0.12.dev9

• Fix: QulacsInvocation._get_qubit_amount now handles OpenQASM string input — when a JS job submits an OpenQASM 2.0 string circuit, the method parses the qreg declaration to extract the qubit count instead of raising "Invalid circuit type!".

v0.0.12.dev8

• Add Sdk.QULACS support in CircuitAdapter._adapt_openqasm with a two-stage fallback strategy:
  1. Qiskit bridge (preferred): parse OpenQASM with QiskitCircuit.from_qasm_str, then convert gate-by-gate to a qulacs.QuantumCircuit via the new CircuitAdapter._qiskit_to_qulacs helper. Fixed gates (H, X, Y, Z, S, Sdg, T, Tdg, CX, CZ, SWAP) use named qulacs methods; parametric and unrecognized gates fall back to qulacs.gate.DenseMatrix with gate.to_matrix().
  2. Raw pass-through (fallback): if qiskit is not installed or conversion raises any exception, the raw OpenQASM string is returned as-is (same approach as Sdk.CUDA_QUANTUM) and a warning is logged.
• Add qulacs as a direct dependency in pyproject.toml.

v0.0.12.dev7

• Fix: remove Sdk.CU_QUANTUM from the CUDA-Q branch in CircuitAdapter._adapt_openqasm — CU_QUANTUM is not a member of the Sdk enum; the only valid CUDA-Q value is Sdk.CUDA_QUANTUM, so the compound sdk in (Sdk.CUDA_QUANTUM, Sdk.CU_QUANTUM) check is replaced with a plain sdk == Sdk.CUDA_QUANTUM.

v0.0.12.dev6

• Fix: replace direct from pytket.extensions.braket import ... and from pytket.extensions.pyquil import ... with importlib.import_module() in CircuitAdapter — avoids IDE static-analysis false positives caused by pytket.extensions being a namespace package populated at runtime by separately installed pytket-braket / pytket-pyquil packages.

v0.0.12.dev5

• Version bump to 0.0.12.dev5.
• Refactor: update logger imports in SubprocessBridge, CircuitAdapter, and SubprocessDispatcher to use relative paths (from ..config.logging_config import logger) for consistency across modules.

v0.0.12.dev4

• Version bumps to 0.0.12.dev4.
• Fix: AsyncInvocationTask._on_task_done now properly fires the step error callback when a background task raises an unhandled exception — reads onErrorCallbackUrl from the event's preparation step and calls update_job_metadata with a structured error response.
• Fix: circuit preparation failure in Invocation.__pre_execute now returns None instead of raising ValueError, allowing the caller to handle the empty result gracefully without an unhandled exception propagating.
• Refactor: replace stdlib logging with the project’s loguru-based logger (via config.logging_config) in SubprocessBridge, CircuitAdapter, and SubprocessDispatcher; all three now call logger.bind(context=__name__).
• Style: reformat SubprocessBridge and SubprocessDispatcher from 2-space to 4-space indentation, consistent with the rest of the codebase.

v0.0.12.dev3

• Version bumps to 0.0.12.dev3.
• Add QUANTUM_HPC SDK enum value (display name "quantum hpc") to support the Quapp HPC backend.
• Make circuitExportUrl optional in Invocation for SDKs that do not require a circuit-export step.

v0.0.12.dev2

• Version bumps to 0.0.12.dev2.
• Fix: correct JavaScript handler runner path in SubprocessDispatcher.RUNNER_MAP — removed the erroneous function/ directory prefix so the subprocess command resolves to handler_runner.js relative to the working directory.

v0.0.12.dev1

• Version bump to 0.0.12.dev1 and dependency update (add qibo, dimod).
• Introduce multi-language SDK support primitives:
  • Language enum for validating and resolving Python/JavaScript runtimes.
  • SubprocessDispatcher for delegating tasks to non-Python runtimes via subprocess with runner configuration and timeout management.
  • SubprocessBridge integrating dispatcher, circuit adapter, and result serializer for JS-Python handler interaction.
  • CircuitAdapter for converting JS subprocess circuit outputs into native SDK formats (OpenQASM, QUBO, JSON) across Qiskit, Braket, PennyLane, etc.
  • ResultSerializer for converting complex job results (numpy, complex numbers, Enums, datetime) into JSON-serializable dictionaries.

v0.0.11.dev7 – v0.0.11.dev10

• 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.