feat(step-through): implement step-through functionality in parser and UI, including button integration and API updates

Author: incrementaliser

src/dylan/dag/word_level_context_dag.py

@@ -277,7 +277,25 @@ def this_is_first_tuple_after_last_word(self) -> None:
     def reset_to_first_tuple_after_last_word(self) -> None:
         """Reset current tuple to the last post-word anchor and clear children."""
         anchor = self.first_tuple_after_last_word or self.root
-        self.set_current_tuple(anchor)
+        path: list[tuple[DAGTuple, GroundableEdge]] = []
+        node = anchor
+        while node != self.root:
+            inc = self._in.get(node)
+            if inc is None:
+                break
+            edge, parent = inc
+            path.append((parent, edge))
+            node = parent
+        path.reverse()
+
+        for parent, _edge in path:
+            for out_edge in self.get_out_edges(parent):
+                out_edge.set_seen(False)
+                out_edge.set_in_context(False)
+
+        self.set_current_tuple(path[0][0] if path else anchor)
+        for _parent, edge in path:
+            edge.traverse(self)
         self.word_stack.clear()
         self.remove_children(self.cur)
         self.exhausted = False
@@ -319,7 +337,7 @@ def get_all_tuples(self) -> list[DAGTuple]:
         return sorted(self._nodes, key=lambda t: t.tuple_id)
 
     def get_n_best_final_tuples(self, n: int) -> list[DAGTuple]:
-        """Return up to *n* complete leaf tuples."""
+        """Return up to *n* complete leaf tuples in creation order, not parser step-through order."""
         leaves = [
             node for node in self.get_all_tuples()
             if self.out_degree(node) == 0 and node.is_complete()

src/dylan/gui/app.py

@@ -514,6 +514,15 @@ def do_parse(_: ft.ControlEvent | None = None) -> None:
             )
             _refresh_views(msg)
 
+        def do_step_through(_: ft.ControlEvent | None = None) -> None:
+            """Advance to the next interpretation from the current parser state."""
+            err, ok = session.run_step_through()
+            if err is not None:
+                append_log(err)
+                return
+            msg = "Stepped to next interpretation." if ok else "No further interpretation available."
+            _refresh_views(msg)
+
         def on_tree_canvas_resize(e: cv.CanvasResizeEvent) -> None:
             """Re-layout the parse tree when the canvas control receives its real size."""
             aw = float(e.width)
@@ -536,6 +545,11 @@ def on_tree_canvas_resize(e: cv.CanvasResizeEvent) -> None:
                 shape=_primary_btn_shape,
             ),
         )
+        step_through_btn = ft.Button(
+            content="Step Through",
+            on_click=do_step_through,
+            tooltip="Advance to the next parse interpretation (Java Step Through)",
+        )
         set_grammar_btn.on_click = pick_grammar_dir
 
         # --- app bar ----------------------------------------------------------
@@ -611,6 +625,7 @@ def on_tree_canvas_resize(e: cv.CanvasResizeEvent) -> None:
                 [
                     sentence_box,
                     parse_btn,
+                    step_through_btn,
                 ],
                 spacing=8,
             ),

src/dylan/gui/parse_session.py

@@ -215,3 +215,10 @@ def run_parse(
         utt = utterance_from_text(speaker, text)
         ok = self.parser.parse_utterance(utt)
         return (None, ok)
+
+    def run_step_through(self) -> tuple[str | None, bool | None]:
+        """Advance to the next parser interpretation, matching Java ``ParserPanel`` step-through."""
+        if self.parser is None:
+            return ("=== Step through ===\nLoad grammar first.", None)
+        ok = self.parser.parse_goal(None)
+        return (None, ok)

src/dylan/parser/dag_parser.py

@@ -180,10 +180,26 @@ def complete(self, word: UtteredWord | None = None) -> DAGTuple:
         dag.add_child(tup, edge)
         return tup
 
+    def get_state_with_n_best_tuples(self, n: int) -> list[DAGTuple]:
+        """Return current tuple plus up to *n* further interpretations by stepping the parser."""
+        if n < 0:
+            raise ValueError("n must be non-negative")
+        dag = self.get_state()
+        dag.reset_to_first_tuple_after_last_word()
+        result: list[DAGTuple] = [dag.get_current_tuple()]
+        try:
+            for _ in range(n):
+                if not self.parse_goal(None):
+                    break
+                result.append(dag.get_current_tuple())
+            return result
+        finally:
+            dag.reset_to_first_tuple_after_last_word()
+
     def get_n_best_final_semantics(self, n: int) -> list[TTRRecordType]:
-        """Return up to *n* final semantics from complete leaf tuples."""
+        """Return final semantics from Java-style N-best tuple stepping."""
         out: list[TTRRecordType] = []
-        for tup in self.get_state().get_n_best_final_tuples(n):
+        for tup in self.get_state_with_n_best_tuples(n):
             sem = tup.get_semantics(self.context)
             ev = sem.evaluate()
             if isinstance(ev, TTRRecordType):
@@ -212,4 +228,5 @@ def parse_word(self, word: UtteredWord) -> WordLevelContextDAG | None:
 DAGParser.completeTree = DAGParser.complete_tree  # type: ignore[attr-defined]
 DAGParser.getFinalSemantics = DAGParser.get_final_semantics  # type: ignore[attr-defined]
 DAGParser.newSentence = DAGParser.new_sentence  # type: ignore[attr-defined]
+DAGParser.getStateWithNBestTuples = DAGParser.get_state_with_n_best_tuples  # type: ignore[attr-defined]
 DAGParser.getNBestFinalSemantics = DAGParser.get_n_best_final_semantics  # type: ignore[attr-defined]

src/dylan/pyodide_api.py

@@ -77,6 +77,17 @@ def dispatch(action: str, payload: dict[str, Any]) -> dict[str, Any]:
             "log_message": format_parse_state_log(msg),
             "views": _view_dict(),
         }
+    if action == "step_through":
+        err, ok = _session.run_step_through()
+        if err is not None:
+            return {"error": err, "step_ok": None, "views": None, "log_message": None}
+        msg = "Stepped to next interpretation." if ok else "No further interpretation available."
+        return {
+            "error": None,
+            "step_ok": ok,
+            "log_message": format_parse_state_log(msg),
+            "views": _view_dict(),
+        }
     return {"error": f"unknown action: {action}"}
 
 

tests/test_pyodide_api.py

@@ -37,6 +37,11 @@ def test_dispatch_load_init_parse_bundled_grammar() -> None:
     assert isinstance(pv, dict)
     assert "man(" in pv.get("semantics", "") and "arrive" in pv.get("semantics", "")
 
+    step_out = pyodide_api.dispatch("step_through", {})
+    assert step_out.get("error") is None
+    assert "step_ok" in step_out
+    assert isinstance(step_out.get("views"), dict)
+
 
 def test_api_json_round_trip() -> None:
     """``api_json`` returns valid JSON and echoes dispatch results."""

web/app.js

@@ -159,6 +159,7 @@ await micropip.install(${JSON.stringify(wheelUrl)})
     document.getElementById("btn-init").disabled = false;
     document.getElementById("btn-new-sentence").disabled = false;
     document.getElementById("btn-parse").disabled = false;
+    document.getElementById("btn-step-through").disabled = false;
   }
 
   async function loadGrammarFromVirtualPath() {
@@ -293,6 +294,18 @@ await micropip.install(${JSON.stringify(wheelUrl)})
         appendLog(String(err));
       }
     });
+    document.getElementById("btn-step-through").addEventListener("click", () => {
+      try {
+        const r = callApi("step_through", {});
+        if (r.error) appendLog(r.error);
+        else {
+          applyViews(r.views);
+          if (r.log_message) appendLog(r.log_message);
+        }
+      } catch (err) {
+        appendLog(String(err));
+      }
+    });
   }
 
   wireTabs();

web/index.html

@@ -54,6 +54,9 @@
             <button type="button" class="btn btn-primary" id="btn-parse" disabled style="align-self: center">
               Parse
             </button>
+            <button type="button" class="btn btn-secondary" id="btn-step-through" disabled style="align-self: center">
+              Step Through
+            </button>
           </div>
           <div class="tabs">
             <div class="tab-bar">