pycat-napari 1.6.330__tar.gz → 1.6.332__tar.gz

{pycat_napari-1.6.330 → pycat_napari-1.6.332}/CHANGELOG.md

@@ -1,3 +1,49 @@
+## [1.6.332] - 2026-07-24
+### Added — **Navigator execution-adapter layer, Phase 1: "Run analysis" computes a plan through the batch handlers, gate-respecting (guided == batch == manual).**
+`selection_scale` Part 2 established there is no uniform "run this op" — but the batch `_STEP_MAP` handlers ARE
+the proven "same computation" route (uniform `(state, image_path, params, output_dir)`; `test_route_equivalence`
+asserts batch == manual). This ships the executor that drives them:
+- New Qt-free **`navigator/executor.py`**: `run_plan(plan, state, …)` executes a compiled plan by driving the
+  batch handlers in the gate-respecting order (`execution.execution_order`), threading each step's output
+  through a shared `state` as a batch replay does. An `ExecAdapter` maps a plan step to a batch handler and
+  derives its params; **a step with no adapter is reported ('needs_panel'), never invoked with guessed
+  arguments** — the whole point of an adapter layer over a generic `fn(image)` (which would produce wrong
+  science silently). Gate semantics are READ from `execution_order`: a blocker halts the run (state untouched),
+  a caveat runs with its reason, probes first.
+- **One proven adapter (`background_removal`)** — the shortest chain `test_route_equivalence` covers — so the
+  acceptance gate is pinned: `tests/navigator/test_navigator_executor.py` (`base`, 5) asserts **guided == batch
+  == manual, bit for bit**, plus a blocker halts + leaves state untouched, a caveat runs, and an uncovered step
+  is reported not invoked.
+- **The Run button is wired** (`run_plan_via_central_manager`, passed as `on_run` from `central_manager`):
+  adapter-covered steps run through the batch handlers; uncovered steps are reported "run these from their
+  method panels, in order". Safe on an uncovered plan (nothing runs); best-effort.
+- **Later phases** (per the `navigator_execution_adapters` spec): a parameter-review panel, more adapters one
+  workflow at a time (each behind its own route-equivalence test), and dock progress/cancel.
+
+## [1.6.331] - 2026-07-24
+### Added — **Save an answered guided plan as a reusable method template (selection_scale Part 3).**
+The navigator's payoff: a plan the user likes should be reusable on other data without re-answering. A guided
+template IS a preset with provenance about how it was authored — so it follows the `analysis_presets`
+discipline (it records the ANSWERS that produced it) but, being a user-level artefact that survives sessions,
+lives in the general `user_settings` service rather than the hardcoded, sensitivity-validated preset registry.
+- New Qt-free **`navigator/templates.py`**: `GuidedTemplate` (name, observables, target, the question trail,
+  step names, parameters) + `template_from_plan` / `save_template` / `list_templates` / `load_template` /
+  `delete_template` / `rename_template` (never overwrites), persisted under `user_settings` key
+  `navigator.templates`.
+- **The verdicts are deliberately NOT stored.** A quality-gate verdict is a property of the DATA, not the
+  plan — a template runnable on one dataset may be blocked on another — so applying a template
+  (`intent_from_template` → recompile against the new context) **re-evaluates every gate**. Carrying a verdict
+  over would assert quality never checked on this data. A corrupt template entry degrades to "not available"
+  (skipped), never a crash.
+- **Reachable**: a '💾 Save as template…' button in the navigator plan view persists the current answers under
+  a user-supplied name.
+- Tests: `tests/navigator/test_navigator_templates.py` (`base`, 7 — save+reload carries steps and answers,
+  applying to a different dataset re-evaluates the gates, verdicts absent, persistence across sessions,
+  delete/rename-never-overwrites, corrupt-degrades) + a dock integration test for the Save button. Full
+  core-or-base green.
+- **Follow-on:** the template-picker UI (start a new analysis FROM a saved template — the apply half's UI; the
+  mechanism is done and tested).
+
 ## [1.6.330] - 2026-07-24
 ### Added — **Gate-respecting execution model for a guided plan, and an actionable run order in the dock (selection_scale Part 2).**
 Part 2 asked to wire the navigator's Run button to execute the compiled plan "through the existing execution

{pycat_napari-1.6.330 → pycat_napari-1.6.332}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pycat-napari
-Version: 1.6.330
+Version: 1.6.332
 Summary: Python Condensate Analysis Toolbox - A napari-based tool for biomolecular condensate analysis
 Project-URL: Homepage, https://github.com/BanerjeeLab-repertoire/pycat-napari
 Project-URL: Repository, https://github.com/BanerjeeLab-repertoire/pycat-napari

{pycat_napari-1.6.330 → pycat_napari-1.6.332}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pycat-napari"
-version = "1.6.330"
+version = "1.6.332"
 description = "Python Condensate Analysis Toolbox - A napari-based tool for biomolecular condensate analysis"
 readme = "README.md"
 # 3.13 is BLOCKED UPSTREAM, not by PyCAT's own code (which compiles and passes core on 3.13).

{pycat_napari-1.6.330 → pycat_napari-1.6.332}/src/pycat/central_manager.py

@@ -119,9 +119,12 @@ class CentralManager:
             getattr(self.menu_manager, 'file_menu', None),
             getattr(getattr(self.viewer, 'window', None), '_qt_window', None))
         # Navigator: guided-analysis dock (question flow -> quality-gated, editable plan). Entry point here,
-        # not the line-capped menu god-file. on_run is left None until the plan-execution bridge lands.
-        from pycat.ui.navigator_dock import install_navigator_action
-        self._navigator_action = install_navigator_action(self.viewer, central_manager=self)
+        # not the line-capped menu god-file. Run analysis is wired through the execution-adapter layer (Phase
+        # 1): adapter-covered steps run via the batch handlers, the rest are reported "run from your panel".
+        from pycat.ui.navigator_dock import install_navigator_action, run_plan_via_central_manager
+        self._navigator_action = install_navigator_action(
+            self.viewer, central_manager=self,
+            on_run=lambda plan: run_plan_via_central_manager(self, plan))
         # Populate the feature registry so any consumer (the beginner home dock, a capability query) sees
         # every surfaced-but-otherwise-hidden feature (navigator inc 4). Guarded: a registration hiccup must
         # never break startup, and the cards' openers import Qt/toolbox lazily so this stays cheap.

pycat_napari-1.6.332/src/pycat/navigator/executor.py

@@ -0,0 +1,163 @@
+"""**Execute a compiled navigator plan by driving the BATCH step handlers** (execution-adapter layer, Phase 1).
+
+`selection_scale` Part 2 established there is no uniform "run this op" — PyCAT operations have bespoke,
+panel-collected signatures. But the **batch `_STEP_MAP` handlers** are the proven "same computation" route:
+they share one signature — ``(state, image_path, params, output_dir)`` — and `test_route_equivalence` already
+asserts they compute byte-identically to the manual GUI route. So the executor drives *those* handlers, in the
+gate-respecting order (`execution.execution_order`), threading each step's output through a shared ``state``
+dict exactly as a batch replay does.
+
+The narrow bridge is per-step: an :class:`ExecAdapter` maps a plan step to a batch handler and derives that
+handler's ``params`` from the answers. A plan step with **no adapter is reported** ("run it from its method
+panel"), never invoked with guessed arguments — a `fn(image)` fallback would pass wrong args and produce wrong
+science silently, which is the whole reason this is an adapter layer and not a loop over ``resolve_operation``.
+
+Phase 1 ships the executor + registry + ONE proven adapter (``background_removal`` — the shortest chain
+`test_route_equivalence` already covers), so `guided == batch == manual` is pinned; later phases add adapters
+one workflow at a time, each earning its place with a route-equivalence test. Qt-free; a runner is optional
+(off-thread when given, synchronous otherwise)."""
+from __future__ import annotations
+
+import dataclasses
+import pathlib
+import tempfile
+from typing import Callable, Optional
+
+from .execution import execution_order
+
+
+@dataclasses.dataclass(frozen=True)
+class ExecAdapter:
+    """Bridges ONE plan step to the batch handler that computes it. ``params_from(intent, ctx, state)`` derives
+    the handler's ``params`` from the answers (Phase 1: grounded defaults; a preset seed lands in Phase 2)."""
+    plan_step: str
+    batch_step: str
+    params_from: Callable
+
+
+def _background_removal_params(intent, ctx, state):
+    radius = None
+    try:
+        radius = ctx.get("ball_radius") if ctx is not None else None
+    except Exception:      # broad-ok: optional_probe — a context miss falls back to the grounded default
+        radius = None
+    return {"ball_radius": int(radius) if radius else 50, "active_layer": "segmentation image"}
+
+
+#: The declared adapters. The ONLY place a plan step is tied to a computation — a step absent here is reported
+#: as "run from its panel", never guessed at. Grows one workflow per phase (each behind a route-equivalence test).
+_ADAPTERS: dict = {
+    "background_removal": ExecAdapter("background_removal", "background_removal", _background_removal_params),
+}
+
+
+def has_adapter(step_name: str) -> bool:
+    return step_name in _ADAPTERS
+
+
+@dataclasses.dataclass(frozen=True)
+class StepOutcome:
+    """What happened to one step. ``outcome`` is ``'ran'`` / ``'ran_with_caveat'`` / ``'blocked'`` (the run
+    stops here) / ``'skipped'`` (after a blocker) / ``'needs_panel'`` (no adapter yet) / ``'error'``."""
+    name: str
+    outcome: str
+    detail: str = ""
+
+
+@dataclasses.dataclass
+class ExecReport:
+    steps: list = dataclasses.field(default_factory=list)
+
+    @property
+    def ran(self) -> list:
+        return [s for s in self.steps if s.outcome.startswith("ran")]
+
+    @property
+    def stopped(self) -> bool:
+        return any(s.outcome in ("blocked", "error") for s in self.steps)
+
+    @property
+    def needs_panel(self) -> list:
+        return [s for s in self.steps if s.outcome == "needs_panel"]
+
+
+def _build_step_registry() -> dict:
+    """The production batch step registry (name → replay handler), built the way `BatchProcessor` does. Only
+    the import-clean `batch_step_registry` is touched (no Qt)."""
+    registry: dict = {}
+
+    class _Recorder:
+        def register_step(self, name, fn):
+            registry[name] = fn
+
+    from pycat.batch_step_registry import register_all_steps
+    register_all_steps(_Recorder())
+    return registry
+
+
+def run_plan(plan, state, *, intent=None, ctx=None, image_path=None, output_dir=None, runner=None,
+             on_step: Optional[Callable] = None) -> ExecReport:
+    """Execute ``plan``'s steps in gate order by driving the batch handlers, threading ``state`` (a dict the
+    handlers read/write, exactly as a batch replay). Returns an :class:`ExecReport`.
+
+    Gate semantics are READ from :func:`execution.execution_order`, never re-decided: a **blocker** stops the
+    run at that step (nothing after it runs); a **caveat** runs with the caveat recorded; **probes** run first.
+    A step with no :class:`ExecAdapter` is reported ``'needs_panel'`` — never invoked with guessed arguments.
+    A step that raises halts the run (downstream depends on its output). ``runner`` (an ``OperationRunner``)
+    runs each handler off the Qt thread when given; otherwise handlers run synchronously (headless / tests)."""
+    intent = intent if intent is not None else getattr(plan, "intent", None)
+    registry = _build_step_registry()
+    report = ExecReport()
+
+    tmp = None
+    if output_dir is None:
+        tmp = tempfile.TemporaryDirectory()
+        output_dir = pathlib.Path(tmp.name)
+    if image_path is None:
+        image_path = pathlib.Path(output_dir) / "sample.tif"
+
+    try:
+        halted = False
+        for es in execution_order(plan):
+            if halted or es.status == "skipped":
+                report.steps.append(StepOutcome(es.name, "skipped", es.reason))
+                continue
+            if es.status == "blocked":
+                report.steps.append(StepOutcome(es.name, "blocked", es.reason))
+                halted = True
+                continue
+
+            adapter = _ADAPTERS.get(es.name)
+            if adapter is None:
+                report.steps.append(StepOutcome(
+                    es.name, "needs_panel", "no execution adapter yet — run this step from its method panel"))
+                if on_step:
+                    on_step(report.steps[-1])
+                continue
+
+            fn = registry.get(adapter.batch_step)
+            if fn is None:
+                report.steps.append(StepOutcome(es.name, "error",
+                                                f"batch step {adapter.batch_step!r} is not registered"))
+                halted = True
+                continue
+
+            params = adapter.params_from(intent, ctx, state)
+            try:
+                if runner is not None:
+                    runner.execute(fn, state, image_path, params, output_dir)
+                else:
+                    fn(state, image_path, params, output_dir)
+            except Exception as exc:      # broad-ok: scientific_result — a failed step halts; report it, never silently continue on stale state
+                report.steps.append(StepOutcome(es.name, "error", f"{type(exc).__name__}: {exc}"))
+                halted = True
+                continue
+
+            report.steps.append(StepOutcome(
+                es.name, "ran_with_caveat" if es.status == "caveat" else "ran", es.reason))
+            if on_step:
+                on_step(report.steps[-1])
+    finally:
+        if tmp is not None:
+            tmp.cleanup()
+    return report

pycat_napari-1.6.332/src/pycat/navigator/templates.py

@@ -0,0 +1,135 @@
+"""**Save an answered guided plan as a reusable method template** (selection_scale Part 3).
+
+The navigator's payoff: the questionnaire produces a plan, and a plan the user likes should be reusable on
+other data without re-answering. A guided template *is* a preset with provenance about how it was authored —
+so it follows the ``analysis_presets`` discipline (it records WHERE it came from: the answers that produced
+it) but is a **user-level, per-session-surviving** artefact, so it lives in the general ``user_settings``
+service rather than the hardcoded, sensitivity-validated ``ANALYSIS_PRESETS`` registry.
+
+**What is stored, and what is deliberately NOT.** A template stores the ANSWERS (the intent: observables,
+target, and the question trail) plus the step names the plan produced and any parameters the user set. It does
+**not** store the quality-gate verdicts. Those are a property of the DATA, not the plan — a template runnable
+on one dataset may be blocked on another — so applying a template re-compiles the intent against the new
+data's context, which re-evaluates every gate. Carrying a verdict over would assert quality that was never
+checked here. A corrupt template entry degrades to "not available" (skipped), never a crash.
+"""
+from __future__ import annotations
+
+import dataclasses
+
+from .contracts import AnalysisIntent
+
+#: user_settings key holding ``{name: serialized_template}``.
+_STORE_KEY = "navigator.templates"
+
+
+@dataclasses.dataclass(frozen=True)
+class GuidedTemplate:
+    """A saved guided plan. ``question`` is the answer trail that produced it — its provenance, so a user
+    revisiting the template can see WHY the steps are there and edit the answers to regenerate rather than
+    hand-edit steps. ``steps`` is the ordered step names the plan produced (for display / provenance);
+    ``parameters`` are any values the user adjusted. Gate verdicts are intentionally absent — they are
+    re-evaluated against the data a template is applied to."""
+    name: str
+    observables: tuple = ()
+    target: str = None
+    question: str = ""
+    steps: tuple = ()
+    parameters: dict = dataclasses.field(default_factory=dict)
+
+
+def template_from_plan(name, intent, plan, *, parameters=None) -> GuidedTemplate:
+    """Build a template from an answered ``intent`` and the ``plan`` it compiled to (the answers + the ordered
+    step names). No verdicts are captured — see the module docstring."""
+    return GuidedTemplate(
+        name=str(name),
+        observables=tuple(getattr(intent, "observables", ()) or ()),
+        target=getattr(intent, "target", None),
+        question=getattr(intent, "question", "") or "",
+        steps=tuple(s.name for s in getattr(plan, "steps", ())),
+        parameters=dict(parameters or {}))
+
+
+def intent_from_template(template) -> AnalysisIntent:
+    """Reconstruct the answers as a fresh :class:`AnalysisIntent`. Compile this against the CURRENT data's
+    context to re-run every quality gate — a template blocked on the new data reports it, because the verdicts
+    were never stored."""
+    return AnalysisIntent(target=template.target, observables=list(template.observables),
+                          question=template.question)
+
+
+# ── persistence via user_settings (survives sessions, applies across datasets) ───────────────────────
+
+def _store(store):
+    if store is not None:
+        return store
+    from pycat.utils.user_settings import settings
+    return settings()
+
+
+def _serialize(t: GuidedTemplate) -> dict:
+    return {"name": t.name, "observables": list(t.observables), "target": t.target,
+            "question": t.question, "steps": list(t.steps), "parameters": dict(t.parameters)}
+
+
+def _deserialize(d) -> "GuidedTemplate | None":
+    try:
+        return GuidedTemplate(
+            name=str(d["name"]),
+            observables=tuple(d.get("observables") or ()),
+            target=d.get("target"),
+            question=str(d.get("question") or ""),
+            steps=tuple(d.get("steps") or ()),
+            parameters=dict(d.get("parameters") or {}))
+    except Exception:      # broad-ok: optional_probe — a corrupt entry degrades to "not available", not a crash
+        return None
+
+
+def _read_all(store) -> dict:
+    raw = _store(store).get(_STORE_KEY, {}) or {}
+    return raw if isinstance(raw, dict) else {}
+
+
+def save_template(template: GuidedTemplate, *, store=None) -> GuidedTemplate:
+    """Persist ``template`` under its name (overwriting a same-named one). Returns it."""
+    s = _store(store)
+    all_ = _read_all(s)
+    all_[template.name] = _serialize(template)
+    s.set(_STORE_KEY, all_)
+    return template
+
+
+def list_templates(*, store=None) -> list:
+    """Every saved template, name-sorted; corrupt entries are skipped (degrade to 'not available')."""
+    out = [_deserialize(v) for v in _read_all(store).values()]
+    return sorted((t for t in out if t is not None), key=lambda t: t.name.lower())
+
+
+def load_template(name, *, store=None):
+    """The named template, or ``None`` if absent or corrupt."""
+    return _deserialize(_read_all(store).get(name))
+
+
+def delete_template(name, *, store=None) -> bool:
+    """Remove the named template. Returns True if it existed."""
+    s = _store(store)
+    all_ = _read_all(s)
+    if name not in all_:
+        return False
+    del all_[name]
+    s.set(_STORE_KEY, all_)
+    return True
+
+
+def rename_template(old_name, new_name, *, store=None) -> bool:
+    """Rename ``old_name`` to ``new_name``. No-op (False) if the source is absent or the target already
+    exists — renaming must never silently overwrite another template."""
+    s = _store(store)
+    all_ = _read_all(s)
+    if old_name not in all_ or new_name in all_ or not str(new_name).strip():
+        return False
+    entry = dict(all_.pop(old_name))
+    entry["name"] = str(new_name)
+    all_[str(new_name)] = entry
+    s.set(_STORE_KEY, all_)
+    return True

{pycat_napari-1.6.330 → pycat_napari-1.6.332}/src/pycat/ui/navigator_dock.py

@@ -128,6 +128,34 @@ def _render_observations(widget, body_layout):
                                  "color: gray; font-size: 10px; margin-bottom: 4px;"))
 
 
+def run_plan_via_central_manager(central_manager, plan):
+    """Execute a compiled plan against the session's data through the execution-adapter layer, and report
+    per-step outcomes. Adapter-covered steps run through the batch handlers (the proven 'same computation'
+    route); a step with no adapter yet is reported as 'run from its panel' — never invoked with guessed args.
+    Safe on an uncovered plan (nothing runs); best-effort, never crashes the UI. This is the wired ``on_run``."""
+    try:
+        from pycat.navigator.executor import run_plan
+        dr = getattr(getattr(central_manager, "active_data_class", None), "data_repository", None)
+        if dr is None:
+            return
+        report = run_plan(plan, dr, ctx=dr)
+        ran = [s.name for s in report.ran]
+        panel = [s.name for s in report.needs_panel]
+        blocked = [s for s in report.steps if s.outcome == "blocked"]
+        parts = []
+        if ran:
+            parts.append("Ran: " + ", ".join(ran) + ".")
+        if blocked:
+            parts.append(f"Stopped at {blocked[0].name} — {blocked[0].detail}")
+        if panel:
+            parts.append("Run these from their method panels, in order: " + ", ".join(panel) + ".")
+        from napari.utils.notifications import show_info
+        show_info(" ".join(parts) or "Nothing to run.")
+    except Exception as exc:      # broad-ok: ui_cleanup — a run attempt must never crash the guided panel
+        from pycat.utils.general_utils import debug_log
+        debug_log("navigator: run_plan_via_central_manager failed", exc)
+
+
 def _guided_run_note(plan):
     """The honest guided-run message, made ACTIONABLE with the gate-respecting run ORDER. Auto-running the
     whole plan needs a per-operation execution adapter (PyCAT ops have bespoke, panel-collected signatures —
@@ -144,6 +172,33 @@ def _guided_run_note(plan):
     return msg + (f", in this order:\n{order}." if order else ".")
 
 
+def _add_template_save(widget, body_layout):
+    """Add a 'Save as template…' button that persists the answered plan under a user-supplied name (the answers
+    + step names, NOT the gate verdicts — see navigator.templates). Reusable on other data without
+    re-answering. Best-effort: a save failure never breaks the plan view."""
+    from PyQt5.QtWidgets import QPushButton, QInputDialog
+
+    def _save():
+        try:
+            name, ok = QInputDialog.getText(widget, "Save guided template", "Template name:")
+            if not ok or not str(name).strip():
+                return
+            from pycat.navigator.templates import template_from_plan, save_template
+            plan = widget._session.compile_plan()
+            save_template(template_from_plan(str(name).strip(), widget._session.intent, plan))
+            from napari.utils.notifications import show_info
+            show_info(f"Saved guided template '{str(name).strip()}' — reuse it on other data from Home.")
+        except Exception as exc:      # broad-ok: ui_cleanup — a save failure must not break the plan view
+            from pycat.utils.general_utils import debug_log
+            debug_log("navigator: could not save the template", exc)
+
+    btn = QPushButton("\U0001f4be  Save as template…")     # 💾
+    btn.setToolTip("Save these answers as a reusable method template — apply it to other data without "
+                   "re-answering (the quality gates re-evaluate on the new data).")
+    btn.clicked.connect(_save)
+    body_layout.addWidget(btn)
+
+
 def build_navigator_widget(session, *, on_run=None, central_manager=None, parent=None):
     """Build (do not mount) the Navigator widget over ``session``, or return ``None`` if Qt is unavailable
     (headless). ``on_run(plan)`` is called when the user runs the compiled plan. When ``central_manager`` is
@@ -226,6 +281,7 @@ def build_navigator_widget(session, *, on_run=None, central_manager=None, parent
         over = QPushButton("↺  Start over")
         over.clicked.connect(_restart)
         body_layout.addWidget(over)
+        _add_template_save(widget, body_layout)
 
     def _answer(spec, value):
         widget._session.answer(spec, value)