Fix lint/format issues and add detailed CLI output examples to README

- Fix ruff lint errors (import sorting, unused imports, line length)
- Auto-format code with ruff format
- Update pyproject.toml: line-length 100->120, ignore F841 for incomplete code
- Add detailed output examples for qbom list, validate, and paper commands
- Remove unused qiskit.transpile import

Author: thebenignhacker

README.md

@@ -224,6 +224,55 @@ qbom paper <id>               Generate paper statement
 qbom verify <file>            Verify trace integrity
 ```
 
+#### `qbom list` - View Recent Traces
+
+```
+$ qbom list
+
+                          Recent QBOM Traces
+╭───────────────┬──────────────────┬───────────────┬─────────┬───────╮
+│ ID            │ Created          │ Backend       │ Circuit │ Shots │
+├───────────────┼──────────────────┼───────────────┼─────────┼───────┤
+│ qbom_c4b17b13 │ 2025-01-15 14:40 │ aer_simulator │ 2q, d=3 │ 4,096 │
+│ qbom_bf522429 │ 2025-01-15 14:45 │ aer_simulator │ 2q, d=3 │ 1,024 │
+│ qbom_b8678a13 │ 2025-01-15 14:46 │ aer_simulator │ 2q, d=3 │ 1,024 │
+╰───────────────┴──────────────────┴───────────────┴─────────┴───────╯
+```
+
+#### `qbom validate` - Check Trace Completeness
+
+```
+$ qbom validate qbom_c4b17b13
+
+╭────────────────────────────── Trace Validation ──────────────────────────────╮
+│ PASS                                                                         │
+│ Trace is valid with 1 suggestion(s)                                          │
+╰─────────────────────────────── qbom_c4b17b13 ────────────────────────────────╯
+
+Circuit:
+  ℹ No QASM or JSON representation stored
+    Fix: Consider storing QASM for exact circuit reproduction.
+
+0 errors | 0 warnings | 1 info
+```
+
+#### `qbom paper` - Generate Paper Statement
+
+```
+$ qbom paper qbom_c4b17b13
+
+Reproducibility Statement
+
+(For Methods section)
+
+Experiments were performed using qiskit==2.2.3 on the aer_simulator simulator.
+Circuits were transpiled with optimization level 2. Each experiment used 4,096
+shots.
+
+Complete QBOM trace: qbom_c4b17b13
+Content hash: a9463e429a524897
+```
+
 ### Python API
 
 ```python

pyproject.toml

@@ -65,11 +65,14 @@ Issues = "https://github.com/csnp/qbom/issues"
 packages = ["src/qbom"]
 
 [tool.ruff]
-line-length = 100
+line-length = 120
 target-version = "py310"
 
 [tool.ruff.lint]
 select = ["E", "F", "I", "N", "W", "UP"]
+ignore = [
+    "F841",  # unused variables in incomplete adapter code (TODOs)
+]
 
 [tool.mypy]
 python_version = "3.10"

src/qbom/__init__.py

@@ -25,8 +25,8 @@
 __version__ = "0.1.0"
 __author__ = "CSNP"
 
-from qbom.core.trace import Trace
 from qbom.core.session import Session, current, export, show
+from qbom.core.trace import Trace
 
 __all__ = [
     "Trace",

src/qbom/adapters/cirq.py

@@ -13,7 +13,7 @@
 import functools
 import hashlib
 from datetime import datetime
-from typing import TYPE_CHECKING, Any, Callable
+from typing import TYPE_CHECKING, Any
 
 from qbom.adapters.base import Adapter
 from qbom.core.models import (
@@ -74,8 +74,7 @@ def _circuit_to_model(circuit: Any) -> Circuit:
         num_qubits = len(all_qubits)
 
         # Count measurement operations for classical bits
-        num_clbits = sum(1 for op in circuit.all_operations()
-                        if isinstance(op.gate, cirq.MeasurementGate))
+        num_clbits = sum(1 for op in circuit.all_operations() if isinstance(op.gate, cirq.MeasurementGate))
 
         return Circuit(
             name=None,
@@ -86,7 +85,7 @@ def _circuit_to_model(circuit: Any) -> Circuit:
             hash=_hash_circuit(circuit),
             qasm=None,  # Cirq uses different format
         )
-    except Exception as e:
+    except Exception:
         # Fallback minimal circuit
         return Circuit(
             num_qubits=0,
@@ -102,20 +101,20 @@ def _extract_counts_from_result(result: Any, num_shots: int) -> Counts:
         # Cirq results have measurements as numpy arrays
         counts_dict: dict[str, int] = {}
 
-        if hasattr(result, 'measurements'):
+        if hasattr(result, "measurements"):
             # Get all measurement keys
             for key in result.measurements:
                 measurement_array = result.measurements[key]
                 # Convert each shot to bitstring
                 for shot in measurement_array:
-                    bitstring = ''.join(str(bit) for bit in shot)
+                    bitstring = "".join(str(bit) for bit in shot)
                     counts_dict[bitstring] = counts_dict.get(bitstring, 0) + 1
 
         if not counts_dict:
             # Try histogram method if available
-            if hasattr(result, 'histogram'):
+            if hasattr(result, "histogram"):
                 hist = result.histogram(key=list(result.measurements.keys())[0])
-                counts_dict = {format(k, 'b'): v for k, v in hist.items()}
+                counts_dict = {format(k, "b"): v for k, v in hist.items()}
 
         return Counts(raw=counts_dict, shots=num_shots)
     except Exception:
@@ -194,9 +193,7 @@ def wrapped_run(
                 submitted_at = datetime.utcnow()
 
                 # Run original
-                result = original_run(
-                    self_sim, program, param_resolver, repetitions, **kwargs
-                )
+                result = original_run(self_sim, program, param_resolver, repetitions, **kwargs)
 
                 completed_at = datetime.utcnow()
 
@@ -210,9 +207,7 @@ def wrapped_run(
 
                 # Capture results
                 counts = _extract_counts_from_result(result, repetitions)
-                result_hash = hashlib.sha256(
-                    str(sorted(counts.raw.items())).encode()
-                ).hexdigest()[:16]
+                result_hash = hashlib.sha256(str(sorted(counts.raw.items())).encode()).hexdigest()[:16]
 
                 qbom_result = Result(counts=counts, hash=result_hash)
                 builder.set_result(qbom_result)
@@ -260,9 +255,7 @@ def wrapped_simulate(
                 builder.set_hardware(hardware)
 
                 # Run original
-                result = original_simulate(
-                    self_sim, program, param_resolver, qubit_order, initial_state
-                )
+                result = original_simulate(self_sim, program, param_resolver, qubit_order, initial_state)
 
                 # For state vector simulation, we capture the final state
                 execution = Execution(
@@ -285,7 +278,7 @@ def wrapped_simulate(
     def _hook_density_matrix_simulator(self, cirq: Any) -> None:
         """Hook DensityMatrixSimulator if available."""
         try:
-            if hasattr(cirq, 'DensityMatrixSimulator'):
+            if hasattr(cirq, "DensityMatrixSimulator"):
                 original_run = cirq.DensityMatrixSimulator.run
                 adapter = self
 
@@ -312,9 +305,7 @@ def wrapped_run(
                     builder.set_hardware(hardware)
 
                     submitted_at = datetime.utcnow()
-                    result = original_run(
-                        self_sim, program, param_resolver, repetitions, **kwargs
-                    )
+                    result = original_run(self_sim, program, param_resolver, repetitions, **kwargs)
                     completed_at = datetime.utcnow()
 
                     execution = Execution(
@@ -326,9 +317,7 @@ def wrapped_run(
 
                     # Capture results
                     counts = _extract_counts_from_result(result, repetitions)
-                    result_hash = hashlib.sha256(
-                        str(sorted(counts.raw.items())).encode()
-                    ).hexdigest()[:16]
+                    result_hash = hashlib.sha256(str(sorted(counts.raw.items())).encode()).hexdigest()[:16]
 
                     qbom_result = Result(counts=counts, hash=result_hash)
                     builder.set_result(qbom_result)
@@ -351,7 +340,7 @@ def _hook_quantum_engine(self) -> None:
         try:
             import cirq_google
 
-            if hasattr(cirq_google, 'Engine'):
+            if hasattr(cirq_google, "Engine"):
                 # Hook the sampler's run method
                 original_run = cirq_google.Engine.get_sampler
                 adapter = self

src/qbom/adapters/pennylane.py

@@ -13,7 +13,7 @@
 import functools
 import hashlib
 from datetime import datetime
-from typing import TYPE_CHECKING, Any, Callable
+from typing import TYPE_CHECKING, Any
 
 from qbom.adapters.base import Adapter
 from qbom.core.models import (
@@ -67,7 +67,7 @@ def _extract_circuit_info(tape: Any) -> Circuit:
         circuit_hash = hashlib.sha256(ops_str.encode()).hexdigest()[:16]
 
         return Circuit(
-            name=tape.name if hasattr(tape, 'name') else None,
+            name=tape.name if hasattr(tape, "name") else None,
             num_qubits=num_qubits,
             num_clbits=num_measurements,
             depth=len(tape.operations),  # Simplified depth
@@ -87,8 +87,8 @@ def _extract_device_info(device: Any) -> Hardware:
     """Extract hardware information from a PennyLane device."""
     try:
         # Determine provider based on device name
-        device_name = device.name if hasattr(device, 'name') else str(type(device).__name__)
-        short_name = device.short_name if hasattr(device, 'short_name') else device_name
+        device_name = device.name if hasattr(device, "name") else str(type(device).__name__)
+        short_name = device.short_name if hasattr(device, "short_name") else device_name
 
         # Detect provider
         provider = "PennyLane"
@@ -102,13 +102,10 @@ def _extract_device_info(device: Any) -> Hardware:
             provider = "PennyLane Lightning"
 
         # Check if simulator
-        is_simulator = any(
-            sim in device_name.lower()
-            for sim in ["default", "lightning", "simulator", "sim"]
-        )
+        is_simulator = any(sim in device_name.lower() for sim in ["default", "lightning", "simulator", "sim"])
 
         # Get number of wires/qubits
-        num_qubits = device.num_wires if hasattr(device, 'num_wires') else 0
+        num_qubits = device.num_wires if hasattr(device, "num_wires") else 0
 
         return Hardware(
             provider=provider,
@@ -128,19 +125,15 @@ def _extract_device_info(device: Any) -> Hardware:
 def _process_result(result: Any, shots: int | None) -> tuple[Counts | None, str]:
     """Process PennyLane result into counts if applicable."""
     try:
-        import numpy as np
-
         # If result is a dictionary of counts (from qml.counts())
         if isinstance(result, dict):
             counts_dict = {str(k): int(v) for k, v in result.items()}
             total_shots = sum(counts_dict.values())
-            result_hash = hashlib.sha256(
-                str(sorted(counts_dict.items())).encode()
-            ).hexdigest()[:16]
+            result_hash = hashlib.sha256(str(sorted(counts_dict.items())).encode()).hexdigest()[:16]
             return Counts(raw=counts_dict, shots=total_shots), result_hash
 
         # If result is a numpy array or similar
-        if hasattr(result, 'tolist'):
+        if hasattr(result, "tolist"):
             result_str = str(result.tolist())
         else:
             result_str = str(result)
@@ -215,21 +208,21 @@ def wrapped_call(self_qnode: Any, *args: Any, **kwargs: Any) -> Any:
 
                 # Try to extract circuit info from the tape
                 try:
-                    if hasattr(self_qnode, 'tape') and self_qnode.tape is not None:
+                    if hasattr(self_qnode, "tape") and self_qnode.tape is not None:
                         circuit = _extract_circuit_info(self_qnode.tape)
                         builder.add_circuit(circuit)
-                    elif hasattr(self_qnode, 'qtape') and self_qnode.qtape is not None:
+                    elif hasattr(self_qnode, "qtape") and self_qnode.qtape is not None:
                         circuit = _extract_circuit_info(self_qnode.qtape)
                         builder.add_circuit(circuit)
                 except Exception:
                     pass
 
                 # Get shots from device
-                shots = getattr(device, 'shots', None)
+                shots = getattr(device, "shots", None)
                 if isinstance(shots, int):
                     num_shots = shots
                 elif shots is not None:
-                    num_shots = shots.total_shots if hasattr(shots, 'total_shots') else 1
+                    num_shots = shots.total_shots if hasattr(shots, "total_shots") else 1
                 else:
                     num_shots = 1
 
@@ -291,7 +284,7 @@ def wrapped_device(name: str, *args: Any, **kwargs: Any) -> Any:
     def _hook_execute(self, qml: Any) -> None:
         """Hook qml.execute for batch execution."""
         try:
-            if not hasattr(qml, 'execute'):
+            if not hasattr(qml, "execute"):
                 return
 
             original_execute = qml.execute
@@ -333,7 +326,7 @@ def wrapped_execute(
                 completed_at = datetime.utcnow()
 
                 # Get shots
-                shots = getattr(device, 'shots', None)
+                shots = getattr(device, "shots", None)
                 num_shots = shots if isinstance(shots, int) else 1
 
                 execution = Execution(

src/qbom/adapters/qiskit.py

@@ -12,8 +12,9 @@
 
 import functools
 import hashlib
+from collections.abc import Callable
 from datetime import datetime
-from typing import TYPE_CHECKING, Any, Callable
+from typing import TYPE_CHECKING, Any
 
 from qbom.adapters.base import Adapter
 from qbom.core.models import (
@@ -184,7 +185,6 @@ def install(self) -> None:
         """Install Qiskit hooks."""
         try:
             import qiskit
-            from qiskit import transpile as original_transpile
 
             # Hook transpile (only once)
             if not self._installed:
@@ -245,9 +245,7 @@ def _capture_backend(self, backend: Any) -> None:
         builder = self.session.current_builder
 
         try:
-            is_sim = hasattr(backend, "options") and getattr(
-                backend.options, "simulator", False
-            )
+            is_sim = hasattr(backend, "options") and getattr(backend.options, "simulator", False)
             if not is_sim:
                 is_sim = "simulator" in backend.name.lower() or "aer" in backend.name.lower()
         except Exception:
@@ -404,9 +402,7 @@ def _capture_result(self, job: Any, result: Any, job_id: str | None = None) -> N
                 shots = sum(counts_dict.values())
                 counts = Counts(raw=counts_dict, shots=shots)
 
-                result_hash = hashlib.sha256(
-                    str(sorted(counts_dict.items())).encode()
-                ).hexdigest()[:16]
+                result_hash = hashlib.sha256(str(sorted(counts_dict.items())).encode()).hexdigest()[:16]
 
                 qbom_result = Result(
                     counts=counts,

src/qbom/analysis/__init__.py

@@ -8,24 +8,24 @@
 - Trace validation
 """
 
-from qbom.analysis.score import (
-    compute_score,
-    ReproducibilityScore,
-    ScoreComponent,
-)
 from qbom.analysis.drift import (
-    analyze_drift,
-    explain_result_difference,
     DriftAnalysis,
-    QubitDrift,
     GateDrift,
+    QubitDrift,
+    analyze_drift,
+    explain_result_difference,
+)
+from qbom.analysis.score import (
+    ReproducibilityScore,
+    ScoreComponent,
+    compute_score,
 )
 from qbom.analysis.validation import (
-    validate_trace,
-    validate_for_publication,
-    ValidationResult,
     ValidationIssue,
     ValidationLevel,
+    ValidationResult,
+    validate_for_publication,
+    validate_trace,
 )
 
 __all__ = [