quapp-braket 0.0.12.dev2__tar.gz → 0.0.12.dev4__tar.gz

{quapp_braket-0.0.12.dev2/quapp_braket.egg-info → quapp_braket-0.0.12.dev4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: quapp-braket
-Version: 0.0.12.dev2
+Version: 0.0.12.dev4
 Summary: Quapp braket library supporting Quapp Platform for Quantum Computing
 Author-email: "CITYNOW Co. Ltd. " <corp@citynow.vn>
 License: The MIT License (MIT)
@@ -19,7 +19,7 @@ Classifier: Programming Language :: Python :: 3
 Requires-Python: >=3.7
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: quapp-common==0.0.13.dev5
+Requires-Dist: quapp-common==0.0.14.dev10
 Requires-Dist: amazon-braket-sdk==1.83.0
 Requires-Dist: oqc-qcaas-client==3.20.0
 Requires-Dist: qiskit==1.4.3

{quapp_braket-0.0.12.dev2 → quapp_braket-0.0.12.dev4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "quapp-braket"
-version = "0.0.12.dev2"
+version = "0.0.12.dev4"
 description = "Quapp braket library supporting Quapp Platform for Quantum Computing"
 readme = "README.md"
 authors = [{ name = "CITYNOW Co. Ltd. ", email = "corp@citynow.vn" }]
@@ -16,7 +16,7 @@ classifiers = [
 ]
 keywords = ["quapp", "quapp-braket", "braket", "quantum"]
 dependencies = [
-    "quapp-common==0.0.13.dev5",
+    "quapp-common==0.0.14.dev10",
     "amazon-braket-sdk==1.83.0",
     "oqc-qcaas-client==3.20.0",
     "qiskit==1.4.3",

quapp_braket-0.0.12.dev4/quapp_braket/__init__.py

@@ -0,0 +1,5 @@
+from .factory.braket_handler_factory import BraketHandlerFactory
+
+# Imported for the side effect: register_rules() has to run before the
+# first job fails, so this import cannot be made lazy.
+from . import error_rules as _error_rules  # noqa: E402,F401

quapp_braket-0.0.12.dev4/quapp_braket/error_rules.py

@@ -0,0 +1,164 @@
+#  Quapp Platform Project
+#  error_rules.py
+#  Copyright © CITYNOW Co. Ltd. All rights reserved.
+
+"""Amazon Braket / OQC-specific error classification rules.
+
+Registered into ``quapp_common.util.error_classifier`` when ``quapp_braket`` is
+imported, so ``quapp-common`` never has to depend on Braket.
+
+Matching is done on the message text or on the class **NAME as a string**, never
+``isinstance``, and nothing from ``braket`` / ``boto3`` / ``qcaas_client`` is
+imported: the classifier has to work even when the SDK is absent.
+
+The first six rules key off messages **this lib itself** raises -- checked against
+the code, not guessed:
+
+    quapp_braket/util/braket_utils.py:97
+        ValueError('Missing required AWS credentials')
+    quapp_braket/model/provider/qapp_braket_provider.py:29
+        ValueError('Unsupported device')
+    quapp_braket/factory/braket_provider_factory.py:39
+        ValueError('Unsupported provider!')
+    quapp_braket/factory/braket_device_factory.py:68
+        ValueError(f'Unsupported device for provider_type=..., sdk=...')
+    quapp_braket/component/backend/braket_invocation.py:126
+        ValueError(f'Invalid circuit type: {type(circuit)}')
+    quapp_braket/async_tasks/braket_circuit_export_task.py:43,50
+        ValueError('Circuit must not be None')
+        ValueError(f'Expected Braket Circuit, got {type(circuit)}')
+    quapp_braket/component/backend/braket_job_fetching.py:88
+        ValueError(f'Invalid {job_type} ARN: {job_id}')
+
+The last two rules match exception names from boto3/botocore and qcaas_client. If
+upstream renames them the rule becomes inert rather than broken -- the classifier
+just falls back on the phase.
+
+One distinction matters here: "the circuit is not a Braket Circuit" is USER_CODE
+(fixing the processing function is enough), while "this device is not supported"
+is PROVIDER_DEVICE (the platform or the function configuration). Both used to be a
+bare ``ValueError``, so both came out under the same label.
+"""
+
+from quapp_common.enum.error_category import ErrorCategory
+from quapp_common.util.error_classifier import Rule, register_rules
+
+DOC_AUTH = 'errors/braket-auth'
+DOC_DEVICE = 'errors/braket-device'
+DOC_CIRCUIT = 'errors/braket-circuit'
+
+
+def _message(exception) -> str:
+    return str(exception).lower()
+
+
+def _name(exception) -> str:
+    return type(exception).__name__
+
+
+register_rules(
+        # ----------------- raised by quapp-braket itself (checked against code)
+        # braket_utils.py:97 -- AWS credentials missing, the user can fix it
+        Rule(match=lambda e: 'missing required aws credentials' in _message(e),
+             category=ErrorCategory.AUTHENTICATION,
+             code='BRAKET_AWS_CREDENTIALS_MISSING',
+             resolution='AWS credentials are missing, so Braket cannot be '
+                        'called.',
+             steps=('Check the AWS access key / secret in your workspace',
+                    'The credential needs braket:* plus s3 access to the result '
+                    'bucket'),
+             doc_slug=DOC_AUTH,
+             retryable=False),
+
+        # braket_invocation.py:126 and braket_circuit_export_task.py:43,50
+        # USER_CODE: fixing the processing function is enough.
+        Rule(match=lambda e: 'invalid circuit type' in _message(e)
+                             or 'expected braket circuit' in _message(e)
+                             or 'circuit must not be none' in _message(e),
+             category=ErrorCategory.USER_CODE,
+             code='BRAKET_INVALID_CIRCUIT_TYPE',
+             resolution='The circuit preparation function did not return a '
+                        'Braket Circuit.',
+             steps=('Check what your processing function returns',
+                    'The circuit must be a braket.circuits.Circuit',
+                    'Returning None is caught here as well'),
+             doc_slug=DOC_CIRCUIT),
+
+        # qapp_braket_provider.py:29, braket_device_factory.py:68,
+        # braket_provider_factory.py:39
+        Rule(match=lambda e: 'unsupported device' in _message(e)
+                             or 'unsupported provider' in _message(e),
+             category=ErrorCategory.PROVIDER_DEVICE,
+             code='BRAKET_DEVICE_UNSUPPORTED',
+             resolution="This device or provider is not supported by Quapp's "
+                        'Braket lib yet.',
+             steps=('Check the device selected for the job',
+                    'quapp-braket serves AWS_BRAKET and OQC_CLOUD'),
+             doc_slug=DOC_DEVICE),
+
+        # braket_job_fetching.py:88 -- malformed ARN
+        Rule(match=lambda e: 'arn:' in _message(e) or 'invalid quantum task arn'
+                             in _message(e) or ' arn: ' in _message(e),
+             category=ErrorCategory.INVALID_INPUT,
+             code='BRAKET_ARN_INVALID',
+             resolution='The quantum task or device ARN is malformed.',
+             steps=('Check the providerJobId sent with the request',
+                    'A Braket ARN looks like '
+                    'arn:aws:braket:<region>:<account>:...'),
+             doc_slug=DOC_DEVICE),
+
+        # ------------------------------------- boto3 / botocore exceptions
+        # AWS quota: kept separate from network errors, because the user has to
+        # request a higher limit rather than just wait and retry.
+        Rule(match=lambda e: _name(e) == 'ClientError'
+                             and ('throttl' in _message(e)
+                                  or 'toomanyrequests' in _message(e)
+                                  or 'limitexceeded' in _message(e)),
+             category=ErrorCategory.QUOTA_EXCEEDED,
+             code='BRAKET_QUOTA_EXCEEDED',
+             resolution='AWS rejected the request: quota exceeded or throttled.',
+             steps=('Wait a few minutes and try again',
+                    'Request a higher Braket service quota if you run many '
+                    'jobs'),
+             retryable=True,
+             retry_after=300),
+
+        Rule(match=lambda e: _name(e) in {'NoCredentialsError',
+                                          'PartialCredentialsError',
+                                          'NoRegionError',
+                                          'UnauthorizedOperation'},
+             category=ErrorCategory.AUTHENTICATION,
+             code='BRAKET_AWS_AUTH_FAILED',
+             resolution='AWS refused to authenticate the Braket request.',
+             steps=('Check that the AWS credential is still valid',
+                    'Check that the configured region actually serves Braket'),
+             doc_slug=DOC_AUTH,
+             retryable=False),
+
+        Rule(match=lambda e: _name(e) in {'EndpointConnectionError',
+                                          'ConnectTimeoutError',
+                                          'ReadTimeoutError',
+                                          'ServiceUnavailable'},
+             category=ErrorCategory.PROVIDER_UNAVAILABLE,
+             code='BRAKET_API_UNAVAILABLE',
+             resolution='The AWS Braket API could not be reached.',
+             steps=('Try again in a few minutes',
+                    'Check the Braket service status in the region you use'),
+             retryable=True,
+             retry_after=120),
+
+        # Placed last: matching is by NAME, so only these exact names land here.
+        Rule(match=lambda e: _name(e) in {'AwsQuantumTaskFailure',
+                                          'DeviceOfflineError',
+                                          'DeviceRetiredError'},
+             category=ErrorCategory.PROVIDER_DEVICE,
+             code='BRAKET_TASK_FAILED',
+             resolution='Braket reports that the quantum task failed, or that '
+                        'the device is unavailable.',
+             steps=('Read the rootCause to see what Braket refused',
+                    'QPU devices have availability windows -- check the '
+                    'device availability'),
+             doc_slug=DOC_DEVICE,
+             retryable=True,
+             retry_after=180),
+)

{quapp_braket-0.0.12.dev2 → quapp_braket-0.0.12.dev4/quapp_braket.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: quapp-braket
-Version: 0.0.12.dev2
+Version: 0.0.12.dev4
 Summary: Quapp braket library supporting Quapp Platform for Quantum Computing
 Author-email: "CITYNOW Co. Ltd. " <corp@citynow.vn>
 License: The MIT License (MIT)
@@ -19,7 +19,7 @@ Classifier: Programming Language :: Python :: 3
 Requires-Python: >=3.7
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: quapp-common==0.0.13.dev5
+Requires-Dist: quapp-common==0.0.14.dev10
 Requires-Dist: amazon-braket-sdk==1.83.0
 Requires-Dist: oqc-qcaas-client==3.20.0
 Requires-Dist: qiskit==1.4.3

{quapp_braket-0.0.12.dev2 → quapp_braket-0.0.12.dev4}/quapp_braket.egg-info/SOURCES.txt

@@ -2,6 +2,7 @@ LICENSE
 README.md
 pyproject.toml
 quapp_braket/__init__.py
+quapp_braket/error_rules.py
 quapp_braket.egg-info/PKG-INFO
 quapp_braket.egg-info/SOURCES.txt
 quapp_braket.egg-info/dependency_links.txt
@@ -36,4 +37,5 @@ quapp_braket/model/provider/qapp_braket_provider.py
 quapp_braket/util/__init__.py
 quapp_braket/util/braket_utils.py
 quapp_braket/util/circuit_convert_utils.py
-quapp_braket/util/provider_job_utils.py
+quapp_braket/util/provider_job_utils.py
+tests/test_error_logging.py

{quapp_braket-0.0.12.dev2 → quapp_braket-0.0.12.dev4}/quapp_braket.egg-info/requires.txt

@@ -1,4 +1,4 @@
-quapp-common==0.0.13.dev5
+quapp-common==0.0.14.dev10
 amazon-braket-sdk==1.83.0
 oqc-qcaas-client==3.20.0
 qiskit==1.4.3

quapp_braket-0.0.12.dev4/tests/test_error_logging.py

@@ -0,0 +1,304 @@
+#  Quapp Platform Project
+#  test_error_logging.py
+#  Copyright © CITYNOW Co. Ltd. All rights reserved.
+
+"""Locks four classes of error-logging bug, all found in real provider-lib code.
+
+1. **A copied hook lost its phase.** Some devices copied ``run_circuit`` /
+   ``_on_execution`` / ``_on_analysis`` wholesale from ``Device`` but dropped the
+   ``with phase(...)`` blocks, so that lib's log had no ``phase`` field at any
+   stage. Same class of bug as ``CustomDevice._on_analysis`` in quapp-common.
+
+2. **The error was flattened into a string.** ``job_response.job_result =
+   {"error": str(exception)}`` leaves the Job Log with a bare string: no
+   category, no phase, no rootCause -- exactly what the ticket complained about.
+
+3. **The error was logged twice.** ``logger.exception()`` immediately before
+   ``build_error_job_response`` emits a second ERROR line for the same failure,
+   skewing every metric that counts job_failed.
+
+4. **A fake job_id.** ``job_logger('SomeClass')`` -- the first argument of
+   ``job_logger()`` is the **job_id**. Passing a class name there sets a fake
+   job_id and it BEATS the real one (``_inject_job_context`` only fills keys that
+   are still None), so filtering by jobId in Grafana loses every line that
+   component logged.
+
+The tests discover files inside the package, so this file works for any lib
+without hardcoding names.
+"""
+
+import ast
+import io
+import pathlib
+import re
+import tokenize
+
+import pytest
+
+REPO_ROOT = pathlib.Path(__file__).resolve().parent.parent
+
+# The first release carrying a phase for analysis/post-processing and one traceId
+# per job.
+MINIMUM_COMMON = '0.0.14.dev6'
+
+# Hooks already instrumented in quapp-common: copying one means copying its
+# phases too. _on_execution creates the job and then talks to the provider, which
+# is why it needs both -- a failed transpile and a rejected job are different
+# errors.
+INSTRUMENTED = {'_on_execution': {'COMPILATION', 'EXECUTION'},
+                '_on_analysis' : {'ANALYSIS'}}
+
+
+def package_root() -> pathlib.Path:
+    """The provider lib's package directory, inferred from the tree.
+
+    A few repos hold more than one package -- quapp-hpc also has
+    ``quapp_slurm_hpc``, which only contains ``runner.py`` for the Slurm node and
+    is not the provider lib. Pick by structural evidence (it has ``model/`` or
+    ``factory/``) rather than by name.
+    """
+    candidates = [d for d in REPO_ROOT.iterdir()
+                  if d.is_dir() and re.fullmatch(r'qu?app_\w+', d.name)
+                  and (d / '__init__.py').is_file()]
+    assert candidates, 'found no package at all'
+
+    if len(candidates) > 1:
+        providers = [d for d in candidates
+                     if (d / 'model').is_dir() or (d / 'factory').is_dir()]
+        assert len(providers) == 1, (
+            f'could not identify the provider package: '
+            f'{providers or candidates}')
+        return providers[0]
+
+    return candidates[0]
+
+
+PACKAGE = package_root()
+
+
+def code_only(path) -> str:
+    """Source with comments stripped out.
+
+    Needed because the explanatory comments *quote* the very code being banned
+    (``{"error": str(exception)}``, ``logger.exception(``). A raw scan would
+    report a false positive on the explanation itself.
+    """
+    source = path.read_text(encoding='utf-8')
+    kept = [token for token in
+            tokenize.generate_tokens(io.StringIO(source).readline)
+            if token.type != tokenize.COMMENT]
+    return tokenize.untokenize(kept)
+
+
+def phases_opened_in(source: str) -> set:
+    """The RuntimePhases opened with ``with phase(...)`` in a piece of code."""
+    tree = ast.parse(source.lstrip())
+    return {
+        argument.attr
+        for node in ast.walk(tree) if isinstance(node, ast.With)
+        for item in node.items if isinstance(item.context_expr, ast.Call)
+        if (getattr(item.context_expr.func, 'id', None)
+            or getattr(item.context_expr.func, 'attr', None)) == 'phase'
+        for argument in item.context_expr.args
+        if isinstance(argument, ast.Attribute)
+    }
+
+
+def python_files():
+    return sorted(PACKAGE.rglob('*.py'))
+
+
+# ------------------------------------------- (1) a copied hook keeps its phases
+
+def test_copied_hooks_keep_their_phases():
+    """Overriding an instrumented hook means copying its `with phase(...)` too."""
+    offenders = []
+    for path in python_files():
+        source = path.read_text(encoding='utf-8')
+        tree = ast.parse(source, filename=str(path))
+        for node in ast.walk(tree):
+            if not isinstance(node, ast.FunctionDef) \
+                    or node.name not in INSTRUMENTED:
+                continue
+            opened = phases_opened_in(ast.get_source_segment(source, node))
+            missing = INSTRUMENTED[node.name] - opened
+            if missing:
+                offenders.append(
+                        f'{path.name}::{node.name} is missing {sorted(missing)}')
+
+    assert not offenders, (
+        f'overridden hooks lost their phase: {offenders}. The original in '
+        f'quapp-common has `with phase(...)`; copying it without that leaves the '
+        f'log with no phase field.')
+
+
+def test_at_least_one_phase_is_opened_somewhere():
+    """A lib that overrides no hook needs none; one that does needs a phase."""
+    overrides = any(
+        isinstance(node, ast.FunctionDef) and node.name in INSTRUMENTED
+        for path in python_files()
+        for node in ast.walk(ast.parse(path.read_text(encoding='utf-8')))
+    )
+    if not overrides:
+        pytest.skip('lib overrides no hook; phases come from quapp-common')
+
+    opened = set()
+    for path in python_files():
+        opened |= phases_opened_in(path.read_text(encoding='utf-8'))
+    assert opened, 'hooks are overridden but no phase is opened'
+
+
+# --------------------------------- (2) no hand-rolled error string
+
+@pytest.mark.parametrize('path', python_files(), ids=lambda p: p.name)
+def test_no_hand_rolled_error_dict(path):
+    """`{"error": str(exception)}` bypasses the entire error envelope."""
+    assert '{"error": str(exception)}' not in code_only(path), (
+        f'{path.name}: flattens the error into a string, losing '
+        f'category/phase/rootCause. Use '
+        f'build_error_job_response(..., phase=..., context=...)')
+
+
+def test_error_envelope_carries_phase_and_context():
+    """Every build_error_job_response in the device needs phase= and context=."""
+    for path in python_files():
+        source = code_only(path)
+        calls = source.count('build_error_job_response(')
+        if not calls:
+            continue
+        assert source.count('phase=RuntimePhase.') >= calls, (
+            f'{path.name}: has {calls} error envelopes but is missing phase=, '
+            f'so the ErrorReport would come out with phase=None')
+        assert source.count('context=self._error_context()') >= calls, (
+            f'{path.name}: error envelope is missing context=, leaving support '
+            f'without the device/provider')
+
+
+# ------------------------------------------ (3) one error is logged once
+
+def test_no_duplicate_error_log_before_envelope():
+    """logger.exception()/logger.error() right before the envelope = 2 ERRORs."""
+    offenders = []
+    for path in python_files():
+        source = code_only(path)
+        for match in re.finditer(r'logger\.(exception|error)\(', source):
+            if 'build_error_job_response(' in source[match.end():match.end() + 400]:
+                line = source[:match.start()].count('\n') + 1
+                offenders.append(f'{path.name}:{line}')
+
+    assert not offenders, (
+        f'duplicate ERROR log before build_error_job_response at {offenders}; '
+        f'the envelope already logs once')
+
+
+# ------------------------------------------------- (4) no fake job_id
+
+@pytest.mark.parametrize('path', python_files(), ids=lambda p: p.name)
+def test_no_fake_job_logger_argument(path):
+    """`job_logger()` takes a real job_id; a component name belongs in `context`.
+
+    Two shapes of fake id are caught: a string literal (`job_logger('Provider')`)
+    and `__name__`, which quietly makes the job_id the dotted module path and
+    blows up jobId cardinality in Grafana as well as losing the real job.
+    """
+    tree = ast.parse(path.read_text(encoding='utf-8'), filename=str(path))
+
+    offenders = []
+    for node in ast.walk(tree):
+        if not isinstance(node, ast.Call) or not node.args:
+            continue
+        if (getattr(node.func, 'id', None)
+                or getattr(node.func, 'attr', None)) != 'job_logger':
+            continue
+        first = node.args[0]
+        if isinstance(first, ast.Constant) and isinstance(first.value, str):
+            offenders.append(repr(first.value))
+        elif isinstance(first, ast.Name) and first.id == '__name__':
+            offenders.append('__name__')
+
+    assert not offenders, (
+        f'{path.name}: job_logger() got {offenders} -- those are fake job_ids. '
+        f"Use logger.bind(context='...') for the component name")
+
+
+def test_providers_bind_their_name_to_context():
+    """A provider that logs must bind its own name, so lines say where they came
+    from."""
+    providers = sorted((PACKAGE / 'model' / 'provider').glob('*.py'))
+    if not providers:
+        pytest.skip('lib has no model/provider directory')
+
+    offenders = []
+    for path in providers:
+        if path.name == '__init__.py':
+            continue
+        # code_only: several providers keep their old logging commented out, and
+        # a raw scan would flag those as if they still logged.
+        source = code_only(path)
+        if 'logger' not in source:
+            continue
+        if not re.search(r"logger\.bind\(context='[A-Za-z]+'\)", source):
+            offenders.append(path.name)
+
+    assert not offenders, (
+        f'providers that log without binding context: {offenders}. The component '
+        f'name must be a field, not text inside the message, or Grafana cannot '
+        f'filter on it')
+
+
+# ------------------------------------------ rules + the quapp-common pin
+
+def test_error_rules_module_exists():
+    assert (PACKAGE / 'error_rules.py').is_file(), \
+        "no error_rules.py, so this SDK's errors never get classified"
+
+
+def test_error_rules_are_registered_on_import():
+    init = (PACKAGE / '__init__.py').read_text(encoding='utf-8')
+    assert 'error_rules' in init, \
+        '__init__.py does not import error_rules, so the rules never register'
+
+
+def test_error_rules_imports_no_vendor_sdk():
+    """The classifier has to run even with the SDK absent, hence name matching."""
+    tree = ast.parse((PACKAGE / 'error_rules.py').read_text(encoding='utf-8'))
+
+    roots = set()
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            roots.update(alias.name.split('.')[0] for alias in node.names)
+        elif isinstance(node, ast.ImportFrom) and node.module and not node.level:
+            roots.add(node.module.split('.')[0])
+
+    assert roots <= {'quapp_common'}, \
+        f'error_rules.py may only import quapp_common, but imports: {sorted(roots)}'
+
+
+def test_common_pin_is_exact_and_current():
+    version = pytest.importorskip('packaging.version')
+
+    text = (REPO_ROOT / 'pyproject.toml').read_text(encoding='utf-8')
+    assert not re.findall(r'"quapp-common\s*(>=|>|~=)', text), (
+        'quapp-common must be pinned with `==`: `>=` lets pip pick a higher '
+        'stable release that is missing the feature (which already happened '
+        'with quapp-qiskit 1.0.14)')
+
+    match = re.search(r'"quapp-common\s*==\s*([^"]+)"', text)
+    assert match, 'no quapp-common pin found'
+    assert version.Version(match.group(1)) >= version.Version(MINIMUM_COMMON), (
+        f'pin {match.group(1)} < {MINIMUM_COMMON}: that release has no phase for '
+        f'analysis/post-processing and still splits one job into two traceIds')
+
+
+def test_registered_rules_are_reachable():
+    """Runs for real: import the lib and read the registry. Skips without the SDK."""
+    package_name = PACKAGE.name
+    pytest.importorskip(package_name)
+    __import__(package_name)
+    from quapp_common.util.error_classifier import registered_rules
+
+    codes = {rule.code for rule in registered_rules()}
+    own = {code for code in codes if not code.startswith(
+            ('INPUT_', 'DEPENDENCY_', 'PROVIDER_', 'HANDLER_', 'PLATFORM_',
+             'COMPILATION_', 'EXECUTION_', 'ANALYSIS_', 'POST_'))}
+    assert own, f'no lib-specific rule registered, only generic ones: {sorted(codes)}'

quapp_braket-0.0.12.dev2/quapp_braket/__init__.py

@@ -1 +0,0 @@
-from .factory.braket_handler_factory import BraketHandlerFactory