Merge pull request #19 from devqubit-labs/refactor/api-refactor

refactor(api): establish UEC as source-of-truth and redesign public API surface

Author: m2papierz

README.md

@@ -8,15 +8,15 @@
 
 **Local-first experiment tracking for quantum computing.** Capture circuits, backend context, and configuration so runs are reproducible, comparable, and easy to share.
 
-> **Status:** Alpha — APIs and bundle formats may evolve in `0.x` releases.
+> **Status:** Alpha – APIs may evolve in `0.x` releases.
 
 ## Why devqubit?
 
-General-purpose experiment trackers (MLflow, Weights & Biases, DVC) are great for logging parameters, metrics, and artifacts. But quantum workloads often need *extra structure* that isn’t first-class there by default: capturing what actually executed (program + compilation), where it executed (backend/device), and how it executed (runtime options).
+General-purpose experiment trackers (MLflow, Weights & Biases, DVC) are great for logging parameters, metrics, and artifacts. But quantum workloads often need *extra structure* that isn't first-class there by default: capturing what actually executed (program + compilation), where it executed (backend/device), and how it executed (runtime options).
 
 | Challenge | MLflow / W&B / DVC | devqubit |
 |-----------|-------------------|----------|
-| **Circuit artifacts** | Generic file logging | Autormatic OpenQASM 3, and SDK-native formats (first-class) |
+| **Circuit artifacts** | Generic file logging | Automatic OpenQASM 3, and SDK-native formats (first-class) |
 | **Device context** | Must be done manually | Automatic backend snapshots, calibration/noise context (first-class) |
 | **Reproducibility** | Depends on what you choose to log | Automatic program + device + execution fingerprints to detect what changed |
 | **Result comparison** | Metric/table-oriented comparisons | Distribution/structural/drift-aware diffs |
@@ -27,13 +27,13 @@ General-purpose experiment trackers (MLflow, Weights & Biases, DVC) are great fo
 
 ## Features
 
-- **Automatic circuit capture** — QPY, OpenQASM 3, and native SDK formats
-- **SDK adapters** — Qiskit, Qiskit Runtime, Amazon Braket, Cirq, PennyLane
-- **Content-addressable storage** — deduplicated artifacts with SHA-256 digests
-- **Reproducibility fingerprints** — detect changes in program, device, or configuration
-- **Run comparison** — TVD analysis, structural diff, drift detection
-- **CI/CD verification** — verify runs against baselines with configurable policies
-- **Portable bundles** — export/import runs as self-contained ZIPs
+- **Automatic circuit capture** – QPY, OpenQASM 3, and native SDK formats
+- **SDK adapters** – Qiskit, Qiskit Runtime, Amazon Braket, Cirq, PennyLane
+- **Content-addressable storage** – deduplicated artifacts with SHA-256 digests
+- **Reproducibility fingerprints** – detect changes in program, device, or configuration
+- **Run comparison** – TVD analysis, structural diff, drift detection
+- **CI/CD verification** – verify runs against baselines with configurable policies
+- **Portable bundles** – export/import runs as self-contained ZIPs
 
 ## Documentation
 
@@ -108,15 +108,15 @@ devqubit diff 01JD7X... 01JD8Y...
 Verify that a run matches an established baseline:
 
 ```python
-from devqubit import verify_against_baseline
+from devqubit import verify_baseline
 from devqubit.compare import VerifyPolicy
 
 policy = VerifyPolicy(
     tvd_threshold=0.05,
     require_same_device=False,
 )
 
-result = verify_against_baseline(
+result = verify_baseline(
     candidate_run_id,
     project="vqe-hydrogen",
     policy=policy,
@@ -199,4 +199,4 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for full guidelines.
 
 ## License
 
-Apache 2.0 — see [LICENSE](LICENSE).
+Apache 2.0 – see [LICENSE](LICENSE).

changelog.d/17.changed.md

@@ -0,0 +1 @@
+Redesigned public API surface: added high-level `verify_baseline()`, new `devqubit.runs` module for run navigation, `devqubit.errors` for public exceptions, `devqubit.adapters` for extension API, moved low-level symbols to appropriate submodules.

docs/concepts/uec.md

@@ -135,7 +135,7 @@ The adapter creates the ExecutionEnvelope and logs it as an artifact. Summary in
 
 ```python
 import json
-from devqubit import create_store, create_registry
+from devqubit.storage import create_store, create_registry
 
 store = create_store()
 registry = create_registry()

docs/guides/comparison.md

@@ -17,9 +17,7 @@ Most users start with the CLI: {doc}`../reference/cli` → `devqubit diff` and `
 Compare two runs to detect differences in parameters, programs, metrics, and results:
 
 ```python
-from devqubit import diff, create_registry
-
-registry = create_registry()
+from devqubit import diff
 
 result = diff("RUN_BASELINE", "RUN_CANDIDATE")
 
@@ -190,20 +188,17 @@ This is more robust than simple O(√k/n) heuristics, especially for non-uniform
 Verify a candidate run against the project's baseline:
 
 ```python
-from devqubit import create_registry
-from devqubit import verify_against_baseline
+from devqubit import verify_baseline
 from devqubit.compare import VerifyPolicy
 
-registry = create_registry()
-
 policy = VerifyPolicy(
     params_must_match=True,
     program_must_match=True,
     noise_factor=1.0,  # Use bootstrap-calibrated threshold
 )
 
-result = verify_against_baseline(
-    candidate=registry.load("RUN_CANDIDATE"),
+result = verify_baseline(
+    "RUN_CANDIDATE",
     project="vqe-h2",
     policy=policy,
 )
@@ -242,13 +237,13 @@ policy = VerifyPolicy(
 | `EITHER` | Pass if exact OR structural matches | General use (default) |
 
 ```python
-from devqubit.compare import VerifyPolicy
+from devqubit.compare import VerifyPolicy, ProgramMatchMode
 
 # Strict reproducibility
-policy = VerifyPolicy(program_match_mode="exact")
+policy = VerifyPolicy(program_match_mode=ProgramMatchMode.EXACT)
 
 # VQE-friendly (ignore parameter values)
-policy = VerifyPolicy(program_match_mode="structural")
+policy = VerifyPolicy(program_match_mode=ProgramMatchMode.STRUCTURAL)
 ```
 
 ### TVD Thresholds
@@ -281,26 +276,36 @@ policy = VerifyPolicy(tvd_max=0.05, noise_factor=1.2)
 ## Setting Baselines
 
 ```python
-from devqubit import create_registry
-
-registry = create_registry()
+from devqubit.runs import get_baseline, set_baseline, clear_baseline
 
 # Set baseline
-registry.set_baseline("vqe-h2", "RUN_PRODUCTION_V1")
+set_baseline("vqe-h2", "RUN_PRODUCTION_V1")
 
 # Get current baseline
-baseline = registry.get_baseline("vqe-h2")
-print(baseline["run_id"])
+baseline = get_baseline("vqe-h2")
+if baseline:
+    print(baseline["run_id"])
+
+# Clear baseline
+clear_baseline("vqe-h2")
+```
+
+Or via CLI:
+
+```bash
+devqubit baseline set vqe-h2 RUN_PRODUCTION_V1
+devqubit baseline get vqe-h2
+devqubit baseline clear vqe-h2
 ```
 
 ## Auto-Promote on Pass
 
 ```python
-result = verify_against_baseline(
-    candidate=candidate,
+from devqubit import verify_baseline
+
+result = verify_baseline(
+    "RUN_CANDIDATE",
     project="vqe-h2",
-    store=store,
-    registry=registry,
     policy=policy,
     promote_on_pass=True,  # Update baseline if verification passes
 )
@@ -313,7 +318,9 @@ result = verify_against_baseline(
 Calibration drift is automatically detected during comparison:
 
 ```python
-result = diff("RUN_A", "RUN_B", registry=registry, store=store)
+from devqubit import diff
+
+result = diff("RUN_A", "RUN_B")
 
 if result.device_drift and result.device_drift.significant_drift:
     print("! Significant calibration drift detected")
@@ -343,10 +350,10 @@ if result.device_drift and result.device_drift.significant_drift:
 ### JUnit Output
 
 ```python
-from devqubit import verify_against_baseline
+from devqubit import verify_baseline
 from devqubit.ci import write_junit
 
-result = verify_against_baseline(...)
+result = verify_baseline("RUN_CANDIDATE", project="vqe-h2")
 write_junit(result, "results.xml")
 ```
 

docs/guides/configuration.md

@@ -146,7 +146,7 @@ import logging
 logging.getLogger("devqubit_engine").setLevel(logging.DEBUG)
 
 # Or for specific modules
-logging.getLogger("devqubit_engine.core.run").setLevel(logging.DEBUG)
+logging.getLogger("devqubit_engine.tracking.run").setLevel(logging.DEBUG)
 ```
 
 Log levels:

docs/guides/remote_storage.md

@@ -37,7 +37,7 @@ export DEVQUBIT_REGISTRY_URL="s3://my-bucket/devqubit"
 
 **Programmatic:**
 ```python
-from devqubit import create_store, create_registry
+from devqubit.storage import create_store, create_registry
 
 store = create_store("s3://my-bucket/devqubit/objects")
 registry = create_registry("s3://my-bucket/devqubit")
@@ -95,6 +95,8 @@ export AWS_DEFAULT_REGION="us-east-1"
 Use the `endpoint_url` parameter for S3-compatible services:
 
 ```python
+from devqubit.storage import create_store
+
 # MinIO
 store = create_store(
     "s3://my-bucket/devqubit/objects",
@@ -140,7 +142,7 @@ export DEVQUBIT_REGISTRY_URL="gs://my-bucket/devqubit"
 
 **Programmatic:**
 ```python
-from devqubit import create_store, create_registry
+from devqubit.storage import create_store, create_registry
 
 store = create_store("gs://my-bucket/devqubit/objects")
 registry = create_registry("gs://my-bucket/devqubit")
@@ -169,8 +171,8 @@ export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account-key.json"
 
 Assign one of these roles to your service account or user:
 
-- `roles/storage.objectAdmin` — Full control of objects
-- `roles/storage.objectCreator` + `roles/storage.objectViewer` — Create and read objects
+- `roles/storage.objectAdmin` – Full control of objects
+- `roles/storage.objectCreator` + `roles/storage.objectViewer` – Create and read objects
 
 Or create a custom role with these permissions:
 - `storage.objects.create`
@@ -206,7 +208,7 @@ Both S3 and GCS use the same object layout:
 You can use different backends for store and registry:
 
 ```python
-from devqubit import create_store, create_registry
+from devqubit.storage import create_store, create_registry
 
 # Objects in S3, metadata locally (faster queries)
 store = create_store("s3://my-bucket/objects")

packages/devqubit-braket/src/devqubit_braket/adapter.py

@@ -12,7 +12,7 @@
 -------
 >>> from braket.circuits import Circuit
 >>> from braket.devices import LocalSimulator
->>> from devqubit_engine.core.run import track
+>>> from devqubit_engine.tracking.run import track
 >>>
 >>> circuit = Circuit().h(0).cnot(0, 1)
 >>>
@@ -36,10 +36,10 @@
 from devqubit_braket.serialization import is_braket_circuit
 from devqubit_braket.tracked import TrackedTask, TrackedTaskBatch
 from devqubit_braket.utils import extract_task_id, get_backend_name
-from devqubit_engine.core.run import Run
-from devqubit_engine.uec.envelope import ExecutionEnvelope
+from devqubit_engine.tracking.run import Run
+from devqubit_engine.uec.models.envelope import ExecutionEnvelope
+from devqubit_engine.utils.common import utc_now_iso
 from devqubit_engine.utils.serialization import to_jsonable
-from devqubit_engine.utils.time_utils import utc_now_iso
 
 
 logger = logging.getLogger(__name__)

packages/devqubit-braket/src/devqubit_braket/calibration.py

@@ -25,12 +25,12 @@
 from typing import Any
 
 from devqubit_braket.utils import get_nested, obj_to_dict, to_float
-from devqubit_engine.uec.calibration import (
+from devqubit_engine.uec.models.calibration import (
     DeviceCalibration,
     GateCalibration,
     QubitCalibration,
 )
-from devqubit_engine.utils.time_utils import utc_now_iso
+from devqubit_engine.utils.common import utc_now_iso
 
 
 def _parse_qubit_key(qubits_key: str) -> list[int]:

packages/devqubit-braket/src/devqubit_braket/envelope.py

@@ -32,32 +32,29 @@
 from devqubit_braket.snapshot import create_device_snapshot
 from devqubit_braket.utils import braket_version, get_adapter_version
 from devqubit_engine.circuit.models import CircuitFormat
-from devqubit_engine.uec.device import DeviceSnapshot
-from devqubit_engine.uec.envelope import ExecutionEnvelope
-from devqubit_engine.uec.execution import ExecutionSnapshot
-from devqubit_engine.uec.producer import ProducerInfo
-from devqubit_engine.uec.program import (
+from devqubit_engine.storage.types import ArtifactRef
+from devqubit_engine.uec.models.device import DeviceSnapshot
+from devqubit_engine.uec.models.envelope import ExecutionEnvelope
+from devqubit_engine.uec.models.execution import ExecutionSnapshot, ProducerInfo
+from devqubit_engine.uec.models.program import (
     ProgramArtifact,
+    ProgramRole,
     ProgramSnapshot,
     TranspilationInfo,
+    TranspilationMode,
 )
-from devqubit_engine.uec.result import (
+from devqubit_engine.uec.models.result import (
     CountsFormat,
     ResultError,
     ResultItem,
     ResultSnapshot,
 )
-from devqubit_engine.uec.types import (
-    ArtifactRef,
-    ProgramRole,
-    TranspilationMode,
-)
+from devqubit_engine.utils.common import utc_now_iso
 from devqubit_engine.utils.serialization import to_jsonable
-from devqubit_engine.utils.time_utils import utc_now_iso
 
 
 if TYPE_CHECKING:
-    from devqubit_engine.core.run import Run
+    from devqubit_engine.tracking.run import Run
 
 
 logger = logging.getLogger(__name__)

packages/devqubit-braket/src/devqubit_braket/snapshot.py

@@ -30,12 +30,12 @@
     get_nested,
     obj_to_dict,
 )
-from devqubit_engine.uec.device import DeviceSnapshot
-from devqubit_engine.utils.time_utils import utc_now_iso
+from devqubit_engine.uec.models.device import DeviceSnapshot
+from devqubit_engine.utils.common import utc_now_iso
 
 
 if TYPE_CHECKING:
-    from devqubit_engine.core.run import Run
+    from devqubit_engine.tracking.run import Run
 
 logger = logging.getLogger(__name__)