fix(ui): harden PA backend against stale qqa wheel (Streamlit Cloud)

The deployed Streamlit instance was pinning qqa==0.5.0 from PyPI (which
predates Population Annealing) instead of the in-tree source, so the PA
button raised "module 'qqa' has no attribute 'population_annealing'".

- Solve page detects PA capability and only offers it when available;
  shows a clear st.warning with the installed qqa version otherwise.
- Visualize page tolerates a missing PAResult symbol via a sentinel.
- Bump qqa to 0.5.2 so pip stops short-circuiting the reinstall.
- Two AppTest regressions monkeypatch the symbols away to lock the fix.

Author: Yuma-Ichikawa

app/pages/1_Solve.py

@@ -40,6 +40,14 @@
 import qqa  # noqa: E402
 from qqa.callbacks import Callback, CallbackState, PopulationTracker  # noqa: E402
 
+# Capability detection — the deployed ``qqa`` wheel is occasionally older
+# than the app source (e.g. Streamlit Community Cloud caches the previous
+# build, or pip resolves ``qqa`` from PyPI when ``.`` install fails). We
+# probe instead of relying on the symbol being present, so the page never
+# crashes with a cryptic ``module 'qqa' has no attribute …`` error.
+PA_AVAILABLE = hasattr(qqa, "population_annealing") and hasattr(qqa, "PAResult")
+QQA_VERSION = getattr(qqa, "__version__", "unknown")
+
 st.set_page_config(page_title="Solve — QQA", page_icon="⚛️", layout="wide")
 sidebar_brand()
 theme_toggle_in_sidebar()
@@ -65,9 +73,10 @@
 
 with st.sidebar:
     st.header("2 · Backend")
+    _backend_options = ["PQQA"] + (["PA (Population Annealing)"] if PA_AVAILABLE else [])
     backend = st.radio(
         "Solver backend",
-        ["PQQA", "PA (Population Annealing)"],
+        _backend_options,
         index=0,
         help=(
             "PQQA = Parallel Quasi-Quantum Annealing (gradient-based, the "
@@ -77,6 +86,14 @@
         ),
         key="solve_backend",
     )
+    if not PA_AVAILABLE:
+        st.warning(
+            f"PA backend not available in this build (qqa = `{QQA_VERSION}`). "
+            "PA needs `qqa.population_annealing`, added in 0.5.1+. "
+            "Re-deploy with the latest source (`pip install -e .` from the "
+            "repo root) or pull a newer wheel.",
+            icon=":material/upgrade:",
+        )
 
 # Hyper-parameter presets — each tuple is
 # (sol_size, epochs, learning_rate, temp, min_bg, max_bg, curve_rate,
@@ -696,6 +713,14 @@ def on_epoch_end(self, state: CallbackState) -> None:
 # Population Annealing (PA) backend
 # =============================================================================
 if run and backend != "PQQA":
+    if not PA_AVAILABLE:
+        st.error(
+            f"Population Annealing is not exposed by the installed `qqa` "
+            f"(version `{QQA_VERSION}`). The deployed wheel is older than this "
+            "Streamlit app — re-deploy with the latest source so "
+            "`qqa.population_annealing` is importable."
+        )
+        st.stop()
     try:
         problem = build_problem(cfg)
     except Exception as e:

app/pages/2_Visualize.py

@@ -22,9 +22,20 @@
 )
 from _solution_viz import render_solution_view  # noqa: E402
 
-from qqa import PAResult  # noqa: E402
 from qqa import visualization as viz  # noqa: E402
 
+# Capability detection — see comment in 1_Solve.py. PAResult only exists
+# from qqa 0.5.1 onwards; older deployed wheels would crash this page on
+# import. We fall back to a sentinel class so ``isinstance`` is False
+# everywhere and the PA-specific tabs simply don't render.
+try:
+    from qqa import PAResult  # noqa: E402
+except ImportError:
+
+    class PAResult:  # type: ignore[no-redef]
+        """Stand-in used when the deployed qqa is too old to expose PAResult."""
+
+
 st.set_page_config(page_title="Visualize — QQA", page_icon="⚛️", layout="wide")
 sidebar_brand()
 theme_toggle_in_sidebar()

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "qqa"
-version = "0.5.1"
+version = "0.5.2"
 description = "Quasi-Quantum Annealing (QQA): a general-purpose GPU solver for combinatorial and spin-glass optimization, with PI-GNN/CPRA and a parallel SA baseline."
 readme = "README.md"
 requires-python = ">=3.10"

requirements.txt

@@ -28,4 +28,12 @@ pandas>=2.0
 streamlit>=1.30
 
 # Install this repository so ``import qqa`` works inside the app.
+# IMPORTANT: must be the LAST line. We bump pyproject.toml's ``version``
+# field on every release that adds a public symbol (e.g. PA was added in
+# 0.5.1, equilibrium-sample/genealogy/Muller-plot in 0.5.2). Without a
+# version bump pip's resolver short-circuits when the previously
+# installed ``qqa`` already matches the pinned spec — Streamlit
+# Community Cloud has been observed to keep ``qqa==0.5.0`` from a stale
+# build and silently skip reinstalling, which then makes
+# ``qqa.population_annealing`` missing at runtime.
 .

tests/test_gui_apptest.py

@@ -270,6 +270,65 @@ def test_solve_page_pa_backend_smoke_run():
     )
 
 
+def test_solve_page_survives_old_qqa_without_population_annealing(monkeypatch):
+    """Regression for ``module 'qqa' has no attribute 'population_annealing'``.
+
+    Reproduces the production bug seen on Streamlit Community Cloud when
+    pip resolved ``qqa==0.5.0`` from PyPI (which predates PA) instead of
+    the in-tree wheel. The Solve page must:
+
+    * not crash on import / first render,
+    * not present PA as a selectable backend, and
+    * surface a human-readable ``st.warning`` explaining the missing
+      capability so the user knows to redeploy.
+    """
+    import qqa as _qqa  # noqa: PLC0415
+
+    monkeypatch.delattr(_qqa, "population_annealing", raising=False)
+    monkeypatch.delattr(_qqa, "PAResult", raising=False)
+
+    at = AppTest.from_file(str(PAGE_DIR / "1_Solve.py"), default_timeout=60)
+    at.session_state["problem_config"] = {
+        "kind": "ising1d",
+        "size": 6,
+        "seed": 0,
+        "device": "cpu",
+        "extra": {},
+    }
+    at.run()
+    assert not at.exception, at.exception
+
+    backend_radios = [r for r in at.sidebar.radio if "backend" in r.label.lower()]
+    assert backend_radios, "Backend radio missing"
+    options = list(backend_radios[0].options)
+    assert "PQQA" in options
+    assert not any("PA" in opt for opt in options), (
+        f"PA option must be hidden when qqa.population_annealing is absent; got {options!r}"
+    )
+
+    warnings = [getattr(w, "body", "") or getattr(w, "value", "") for w in at.warning]
+    assert any("PA backend not available" in (b or "") for b in warnings), (
+        f"Capability-missing warning not shown; warnings={warnings!r}"
+    )
+
+
+def test_visualize_page_survives_old_qqa_without_pa_result(monkeypatch):
+    """Visualize page must not crash if the deployed qqa lacks ``PAResult``.
+
+    Older wheels (pre-0.5.1) do not expose ``PAResult``; the page used to
+    do a top-level ``from qqa import PAResult`` which would raise on
+    import. The hardened page now degrades gracefully — it should render
+    the empty state when no run is loaded, instead of crashing.
+    """
+    import qqa as _qqa  # noqa: PLC0415
+
+    monkeypatch.delattr(_qqa, "PAResult", raising=False)
+
+    at = AppTest.from_file(str(PAGE_DIR / "2_Visualize.py"), default_timeout=60)
+    at.run()
+    assert not at.exception, at.exception
+
+
 def test_solve_runs_with_default_mis():
     """Regression for the duplicate-element-key crash on the default MIS
     problem.