batchgrid 0.1.0b1__tar.gz → 0.2.0b2__tar.gz

{batchgrid-0.1.0b1 → batchgrid-0.2.0b2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: batchgrid
-Version: 0.1.0b1
+Version: 0.2.0b2
 Summary: Run a prompt, or a whole pipeline, over every row of a DataFrame or spreadsheet - with cost estimates, retries and resumable runs.
 Project-URL: Homepage, https://github.com/mertguvencli/batchgrid
 Project-URL: Source, https://github.com/mertguvencli/batchgrid/tree/main/python
@@ -81,6 +81,47 @@ result = batchgrid.run("next_week.csv", plan="sentiment.json", max_cost=10)
 
 The file is the same one `batchgrid --save-plan` writes and `batchgrid --plan` reads.
 
+## In the browser
+
+`batchgrid.ui()` opens the batchgrid workspace with your data in the sheet. In a Jupyter notebook it
+shows in the cell's output; elsewhere, or with `inline=False`, it opens in your browser. You can
+chat, check the plan and run it there, while the log prints in the notebook cell or terminal as it
+happens:
+
+```python
+df2 = batchgrid.ui(df)
+```
+
+```
+batchgrid is open at http://127.0.0.1:4817
+
+❯ classify the sentiment of each review
+  ✔ Reading data.csv - 1,000 rows · 1 column: review
+  ✔ Asking gpt-5.6 for a plan - 1 step · 2.1k tokens
+  ✔ Estimating the cost - About ~$0.08 for 1,000 rows
+batchgrid: 100%|██████████| 1000/1000 [00:42<00:00, failed=0]
+  ✔ 1000/1000 rows, 0 failed
+  ↳ Sheet synced: 1,000 rows × 2 columns
+
+Finished in the browser.
+```
+
+To come back, press **Finish** in the workspace, close its tab, or interrupt the cell. Once it stops,
+a note takes the workspace's place in the cell. `ui()` returns the
+sheet as the tab last showed it. For a DataFrame, that is a copy of yours with the new columns and
+any cells you edited; untouched columns keep their dtypes. `ui()` with no data starts on an empty
+sheet.
+
+The workspace runs on your machine and uses the keys from `batchgrid config` or your environment. Your
+browser has to be able to reach the machine running Python, so this does not work for a notebook on
+a remote server.
+
+From a terminal, the `batchgrid` command this package installs does the same:
+
+```bash
+batchgrid ui data.csv     # or: batchgrid --ui data.csv
+```
+
 ## Reference
 
 ### `batchgrid.run(data, prompt=None, *, plan=None, ...) -> Result`
@@ -124,6 +165,12 @@ except KeyboardInterrupt:
     result = batchgrid.resume(df)
 ```
 
+### `batchgrid.ui(data=None, *, inline=None, height=720, open_browser=True, port=None, log=True) -> DataFrame | None`
+
+See [In the browser](#in-the-browser). `inline` shows the workspace in the cell, `height` pixels tall;
+by default it does in a Jupyter notebook and opens a browser tab anywhere else. `on_event` receives the same events as in `run()`, plus `ui`,
+`sheet`, `browser_error` and `closed`.
+
 ### Errors
 
 Everything raises `batchgrid.BatchgridError`, and its `code` says what went wrong:
@@ -140,12 +187,14 @@ Everything raises `batchgrid.BatchgridError`, and its `code` says what went wron
 
 ### Choosing the CLI
 
-The package looks for the CLI in this order:
+The `batchgrid` command pip installs hands everything to the Node CLI, so `batchgrid config`,
+`batchgrid ui` and the rest work the same whether batchgrid came from pip or npm. The package looks
+for the CLI in this order:
 
 1. the `cli=[...]` argument
 2. the `BATCHGRID_CLI` environment variable, e.g. `node /path/to/cli/dist/index.js`
-3. a `batchgrid` on the PATH
-4. `npx "batchgrid@>=0.2.0 <1"`
+3. the npm `batchgrid` on the PATH (never this package's own command)
+4. `npx "batchgrid@>=0.3.0 <1"`
 
 ## Development
 

{batchgrid-0.1.0b1 → batchgrid-0.2.0b2}/README.md

@@ -55,6 +55,47 @@ result = batchgrid.run("next_week.csv", plan="sentiment.json", max_cost=10)
 
 The file is the same one `batchgrid --save-plan` writes and `batchgrid --plan` reads.
 
+## In the browser
+
+`batchgrid.ui()` opens the batchgrid workspace with your data in the sheet. In a Jupyter notebook it
+shows in the cell's output; elsewhere, or with `inline=False`, it opens in your browser. You can
+chat, check the plan and run it there, while the log prints in the notebook cell or terminal as it
+happens:
+
+```python
+df2 = batchgrid.ui(df)
+```
+
+```
+batchgrid is open at http://127.0.0.1:4817
+
+❯ classify the sentiment of each review
+  ✔ Reading data.csv - 1,000 rows · 1 column: review
+  ✔ Asking gpt-5.6 for a plan - 1 step · 2.1k tokens
+  ✔ Estimating the cost - About ~$0.08 for 1,000 rows
+batchgrid: 100%|██████████| 1000/1000 [00:42<00:00, failed=0]
+  ✔ 1000/1000 rows, 0 failed
+  ↳ Sheet synced: 1,000 rows × 2 columns
+
+Finished in the browser.
+```
+
+To come back, press **Finish** in the workspace, close its tab, or interrupt the cell. Once it stops,
+a note takes the workspace's place in the cell. `ui()` returns the
+sheet as the tab last showed it. For a DataFrame, that is a copy of yours with the new columns and
+any cells you edited; untouched columns keep their dtypes. `ui()` with no data starts on an empty
+sheet.
+
+The workspace runs on your machine and uses the keys from `batchgrid config` or your environment. Your
+browser has to be able to reach the machine running Python, so this does not work for a notebook on
+a remote server.
+
+From a terminal, the `batchgrid` command this package installs does the same:
+
+```bash
+batchgrid ui data.csv     # or: batchgrid --ui data.csv
+```
+
 ## Reference
 
 ### `batchgrid.run(data, prompt=None, *, plan=None, ...) -> Result`
@@ -98,6 +139,12 @@ except KeyboardInterrupt:
     result = batchgrid.resume(df)
 ```
 
+### `batchgrid.ui(data=None, *, inline=None, height=720, open_browser=True, port=None, log=True) -> DataFrame | None`
+
+See [In the browser](#in-the-browser). `inline` shows the workspace in the cell, `height` pixels tall;
+by default it does in a Jupyter notebook and opens a browser tab anywhere else. `on_event` receives the same events as in `run()`, plus `ui`,
+`sheet`, `browser_error` and `closed`.
+
 ### Errors
 
 Everything raises `batchgrid.BatchgridError`, and its `code` says what went wrong:
@@ -114,12 +161,14 @@ Everything raises `batchgrid.BatchgridError`, and its `code` says what went wron
 
 ### Choosing the CLI
 
-The package looks for the CLI in this order:
+The `batchgrid` command pip installs hands everything to the Node CLI, so `batchgrid config`,
+`batchgrid ui` and the rest work the same whether batchgrid came from pip or npm. The package looks
+for the CLI in this order:
 
 1. the `cli=[...]` argument
 2. the `BATCHGRID_CLI` environment variable, e.g. `node /path/to/cli/dist/index.js`
-3. a `batchgrid` on the PATH
-4. `npx "batchgrid@>=0.2.0 <1"`
+3. the npm `batchgrid` on the PATH (never this package's own command)
+4. `npx "batchgrid@>=0.3.0 <1"`
 
 ## Development
 

{batchgrid-0.1.0b1 → batchgrid-0.2.0b2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "batchgrid"
-version = "0.1.0b1"
+version = "0.2.0b2"
 description = "Run a prompt, or a whole pipeline, over every row of a DataFrame or spreadsheet - with cost estimates, retries and resumable runs."
 readme = "README.md"
 license = "MIT"
@@ -26,6 +26,9 @@ pandas = ["pandas>=1.5"]
 progress = ["tqdm>=4.60"]
 dev = ["pytest>=7", "pandas>=1.5"]
 
+[project.scripts]
+batchgrid = "batchgrid._cli:main"
+
 [project.urls]
 Homepage = "https://github.com/mertguvencli/batchgrid"
 Source = "https://github.com/mertguvencli/batchgrid/tree/main/python"

{batchgrid-0.1.0b1 → batchgrid-0.2.0b2}/src/batchgrid/__init__.py

@@ -5,15 +5,18 @@
     result = batchgrid.run(df, "classify the sentiment of each review", max_cost=5)
     result.data  # df with the new columns
 
+    df2 = batchgrid.ui(df)  # the same, in the browser; its log prints here
+
 The work is done by the batchgrid CLI (Node.js 22+), which this package starts
 and follows; see find_cli() for how it is located.
 """
 
 from ._api import Plan, Result, plan, resume, run
+from ._ui import ui
 from ._cli import CLI_SPEC, find_cli
 from .errors import BatchgridError, CostLimitError, MissingSecretsError, NoPlanError
 
-__version__ = "0.1.0b1"
+__version__ = "0.2.0b2"
 
 __all__ = [
     "BatchgridError",
@@ -27,4 +30,5 @@ __all__ = [
     "plan",
     "resume",
     "run",
+    "ui",
 ]

{batchgrid-0.1.0b1 → batchgrid-0.2.0b2}/src/batchgrid/_cli.py

@@ -14,12 +14,13 @@ import shutil
 import signal
 import subprocess
 import sys
+import sysconfig
 import threading
 from collections import deque
 from typing import Callable, Deque, Dict, Iterator, List, Mapping, Optional, Sequence
 
-#: The CLI releases this package speaks to: 0.2.0 was the first with ``--json``, and its events only gain fields
-CLI_SPEC = "batchgrid@>=0.2.0 <1"
+#: The CLI releases this package speaks to: 0.3.0 was the first with ``ui``, and its events only gain fields
+CLI_SPEC = "batchgrid@>=0.3.0 <1"
 
 Event = Dict[str, object]
 
@@ -36,7 +37,7 @@ def find_cli(cli: Optional[Sequence[str]] = None) -> List[str]:
     from_env = os.environ.get("BATCHGRID_CLI", "").strip()
     if from_env:
         return shlex.split(from_env, posix=os.name != "nt")
-    installed = shutil.which("batchgrid")
+    installed = _node_cli_on_path()
     if installed:
         return [installed]
     npx = shutil.which("npx")
@@ -51,6 +52,49 @@ def find_cli(cli: Optional[Sequence[str]] = None) -> List[str]:
     )
 
 
+def _node_cli_on_path() -> Optional[str]:
+    """The npm ``batchgrid`` on the PATH - not this package's own ``batchgrid``
+    command, which only hands over to it and would otherwise call itself."""
+    scripts = os.path.normcase(os.path.realpath(sysconfig.get_path("scripts") or ""))
+    for directory in os.environ.get("PATH", "").split(os.pathsep):
+        found = shutil.which("batchgrid", path=directory) if directory else None
+        if not found:
+            continue
+        if os.path.normcase(os.path.realpath(os.path.dirname(found))) == scripts or _is_python_script(found):
+            continue
+        return found
+    return None
+
+
+def _is_python_script(path: str) -> bool:
+    try:
+        with open(path, "rb") as fh:
+            first = fh.readline(200)
+    except OSError:
+        return False
+    return first.startswith(b"#!") and b"python" in first
+
+
+def main(argv: Optional[Sequence[str]] = None) -> int:
+    """The ``batchgrid`` command pip installs: the Node CLI, with the same arguments.
+
+    So ``batchgrid ui data.csv`` (or ``batchgrid --ui data.csv``) and every
+    other command work the same whether batchgrid came from pip or npm.
+    """
+    args = list(sys.argv[1:] if argv is None else argv)
+    try:
+        command = find_cli()
+    except Exception as err:  # noqa: BLE001 - the message is the whole story here
+        print(f"batchgrid: {err}", file=sys.stderr)
+        return 1
+    if os.name != "nt":
+        # Become the CLI: its exit code, its signals, its terminal
+        os.execvp(command[0], [*command, *args])
+    # Ctrl+C reaches the CLI directly; this process only waits for it
+    signal.signal(signal.SIGINT, signal.SIG_IGN)
+    return subprocess.call([*command, *args])
+
+
 def stream_events(
     command: Sequence[str],
     args: Sequence[str],

batchgrid-0.2.0b2/src/batchgrid/_ui.py

@@ -0,0 +1,244 @@
+"""ui() - the web workspace in the notebook or the browser, with its log here and its sheet coming back."""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Callable, List, Mapping, Optional, Sequence
+
+from ._api import Data, EventHandler, _input_file, _is_dataframe, _merge_output, _TempDir
+from ._cli import Event, find_cli, stream_events
+from .errors import BatchgridError
+
+if TYPE_CHECKING:
+    import pandas as pd
+
+
+def ui(
+    data: Optional[Data] = None,
+    *,
+    inline: Optional[bool] = None,
+    height: int = 720,
+    open_browser: bool = True,
+    port: Optional[int] = None,
+    log: bool = True,
+    on_event: Optional[EventHandler] = None,
+    cli: Optional[Sequence[str]] = None,
+    env: Optional[Mapping[str, str]] = None,
+) -> Optional["pd.DataFrame"]:
+    """Open the batchgrid workspace and wait until you are done there.
+
+    ``data`` - a file path or a pandas DataFrame - opens in the sheet. In a
+    Jupyter notebook the workspace shows in the cell's output, ``height``
+    pixels tall; ``inline=False`` opens it in a browser tab instead, which is
+    what happens outside a notebook. Chat, plan and run there; what happens is
+    printed here as it happens, with a progress bar while rows run.
+
+    Press Finish in the workspace, close its tab, or interrupt the cell
+    (Ctrl+C) to come back. The sheet as the tab last showed it is returned as a DataFrame: for
+    a DataFrame you passed in, a copy with the new columns added and your
+    edits in it. None when nothing was opened, or pandas is not installed.
+
+    It runs on this machine, so it needs a browser that can reach it - not a
+    notebook running on a remote server.
+    """
+    embed = _in_notebook() if inline is None else inline
+    frame_view = _Frame(height) if embed else None
+    printer = _Printer(link=not embed) if log else None
+    with _input_file(data) as (path, frame):
+        out = _TempDir()
+        try:
+            sheet = os.path.join(out.get(), "sheet.csv")
+            args: List[str] = ["ui", *([path] if path else []), "--output", sheet, "--json"]
+            if embed or not open_browser:
+                args.append("--no-open")
+            if port is not None:
+                args += ["--port", str(port)]
+
+            failure: Optional[Event] = None
+            started = False
+            ended: Optional[Event] = None
+            try:
+                for event in stream_events(find_cli(cli), args, env):
+                    if event.get("type") == "error":
+                        failure = event
+                    elif event.get("type") == "ui":
+                        started = True
+                        if frame_view is not None:
+                            frame_view.show(str(event.get("url")))
+                    elif event.get("type") == "exit":
+                        ended = event
+                    if printer is not None:
+                        printer.show(event)
+                    if on_event is not None and event.get("type") != "exit":
+                        on_event(event)
+            except KeyboardInterrupt:
+                # Interrupting is how a notebook says "done": the server has stopped, the sheet is what it was
+                pass
+            finally:
+                if printer is not None:
+                    printer.close()
+                if frame_view is not None:
+                    frame_view.close()
+            if failure is not None:
+                raise BatchgridError(str(failure.get("code")), str(failure.get("message")))
+            if not started and ended is not None and ended.get("code"):
+                stderr = str(ended.get("stderr") or "")
+                hint = " The installed batchgrid CLI is too old for ui() - update it." if "unknown" in stderr else ""
+                raise BatchgridError("cli_failed", f"batchgrid ui did not start.{hint}\n{stderr}".rstrip(), stderr)
+            return _read_sheet(frame, Path(sheet), Path(path) if path else None)
+        finally:
+            out.cleanup()
+
+
+def _read_sheet(frame: Any, sheet: Path, sent: Optional[Path]) -> Optional["pd.DataFrame"]:
+    """The sheet as the tab last showed it.
+
+    For a DataFrame passed in, a copy of it: new columns are added, a column
+    edited in the tab takes the edited values, and a column left alone keeps
+    its dtype. When the tab reshaped the sheet, it comes back as it was shown.
+    """
+    if not sheet.exists():
+        return None
+    try:
+        import pandas as pd
+    except ImportError:
+        return None
+    if frame is None or not _is_dataframe(frame) or sent is None:
+        return pd.read_csv(sheet, dtype=str, keep_default_na=False)
+
+    merged = _merge_output(frame, sheet)
+    shown = pd.read_csv(sheet, dtype=str, keep_default_na=False)
+    if merged is None or len(shown) != len(frame) or list(merged.columns[: len(frame.columns)]) != [str(c) for c in frame.columns]:
+        return merged
+    # What the tab was given, as text - the same text it would hand back for an untouched cell
+    given = pd.read_csv(sent, dtype=str, keep_default_na=False)
+    for column in given.columns:
+        if column in shown.columns and not shown[column].equals(given[column]):
+            merged[column] = shown[column].to_numpy()
+    return merged
+
+
+def _in_notebook() -> bool:
+    """Whether this runs in a Jupyter kernel, whose front end can show the workspace in a cell"""
+    try:
+        from IPython import get_ipython
+
+        shell = get_ipython()
+        return shell is not None and "IPKernelApp" in shell.config
+    except Exception:  # noqa: BLE001 - no IPython means a plain console
+        return False
+
+
+class _Frame:
+    """The workspace in the cell's output; once it stops, a note takes its place"""
+
+    def __init__(self, height: int) -> None:
+        self.height = height
+        self.handle: Any = None
+
+    def show(self, url: str) -> None:
+        from IPython.display import IFrame, display
+
+        self.handle = display(
+            IFrame(
+                url,
+                width="100%",
+                height=self.height,
+                extras=[
+                    'style="border: 1px solid rgba(128, 128, 128, 0.35); border-radius: 6px"',
+                    'allow="clipboard-read; clipboard-write"',
+                ],
+            ),
+            display_id=True,
+        )
+
+    def close(self) -> None:
+        if self.handle is None:
+            return
+        from IPython.display import HTML
+
+        # The server behind the frame is gone, so a saved notebook keeps no dead workspace
+        self.handle.update(HTML("<em>batchgrid closed. Run the cell again to reopen it.</em>"))
+        self.handle = None
+
+
+class _Printer:
+    """The terminal's log, in a notebook cell or a Python console"""
+
+    def __init__(self, link: bool = True) -> None:
+        self.bar: Any = None
+        self.link = link
+        try:
+            from tqdm.auto import tqdm
+
+            self._tqdm: Optional[Callable[..., Any]] = tqdm
+        except ImportError:
+            self._tqdm = None
+
+    def show(self, event: Event) -> None:
+        kind = event.get("type")
+        if kind == "progress":
+            self._progress(event)
+            return
+        # Anything else ends the run's bar, so its lines are not drawn over it
+        if kind in ("result", "closed", "user", "plan"):
+            self.close()
+        if kind == "ui" and self.link:
+            self._link(str(event.get("url")))
+        elif kind == "user":
+            self._line(f"\n❯ {event.get('text')}")
+        elif kind == "trace":
+            mark = {"error": "✖", "stopped": "⊘"}.get(str(event.get("status")), "✔")
+            detail = f" - {event['detail']}" if event.get("detail") else ""
+            self._line(f"  {mark} {event.get('text')}{detail}")
+        elif kind == "message":
+            self._line(f"  {event.get('text')}")
+        elif kind == "plan":
+            self._line(f"\n{event.get('summary')}\n")
+            if event.get("costFormatted"):
+                self._line(str(event.get("costFormatted")))
+        elif kind == "result":
+            mark = {"done": "✔", "stopped": "⊘"}.get(str(event.get("status")), "✖")
+            self._line(f"  {mark} {event.get('success')}/{event.get('total')} rows, {event.get('failed')} failed")
+        elif kind == "sheet":
+            columns = event.get("columns") or []
+            self._line(f"  ↳ Sheet synced: {event.get('rows')} rows × {len(columns)} columns")  # type: ignore[arg-type]
+        elif kind == "browser_error":
+            self._line(f"  ✖ Browser: {event.get('message')}")
+        elif kind == "error":
+            self._line(f"✖ {event.get('message')}")
+        elif kind == "closed":
+            why = {"tab_closed": "The tab was closed", "finished": "Finished in the browser" if self.link else "Finished"}.get(
+                str(event.get("reason")), "Stopped"
+            )
+            self._line(f"\n{why}.")
+
+    def _progress(self, event: Event) -> None:
+        if self._tqdm is None:
+            return
+        total = int(event.get("total") or 0)  # type: ignore[arg-type]
+        if self.bar is None:
+            self.bar = self._tqdm(total=total, unit="row", desc="batchgrid")
+        if total and self.bar.total != total:
+            self.bar.total = total
+        self.bar.n = int(event.get("completed") or 0)  # type: ignore[arg-type]
+        self.bar.set_postfix(failed=int(event.get("failed") or 0), refresh=False)  # type: ignore[arg-type]
+        self.bar.refresh()
+
+    def _link(self, url: str) -> None:
+        if _in_notebook():
+            from IPython.display import HTML, display
+
+            display(HTML(f'batchgrid is open at <a href="{url}" target="_blank">{url.split("?")[0]}</a>'))
+            return
+        self._line(f"batchgrid is open at {url}")
+
+    def _line(self, text: str) -> None:
+        print(text, flush=True, file=sys.stdout)
+
+    def close(self) -> None:
+        if self.bar is not None:
+            self.bar.close()
+            self.bar = None

batchgrid-0.2.0b2/tests/test_ui.py

@@ -0,0 +1,196 @@
+"""ui() against the real CLI server, with this test standing in for the browser tab.
+
+The tab's side is plain HTTP - the same requests the web workspace sends - so
+the whole path from Python through the CLI and back is exercised without a
+browser: the link, the log, the synced sheet, and each way of finishing.
+"""
+
+from __future__ import annotations
+
+import _thread
+import json
+import os
+import stat
+import sys
+import threading
+import time
+import types
+import urllib.request
+from pathlib import Path
+from typing import Any, Dict, List
+
+import pandas as pd
+import pytest
+
+import batchgrid
+from batchgrid._cli import _node_cli_on_path
+
+pytestmark = pytest.mark.usefixtures("cli_env")
+
+
+class FakeTab:
+    """What the web workspace does once `batchgrid ui` opens it"""
+
+    def __init__(self, url: str) -> None:
+        self.url = url
+        self.base = url.split("/?")[0]
+        self.token = url.split("token=")[1]
+        self.stream: Any = None
+
+    def call(self, path: str, body: Any = None) -> Any:
+        data = None if body is None else json.dumps(body).encode()
+        request = urllib.request.Request(
+            f"{self.base}/__batchgrid/{path}",
+            data=data,
+            method="POST" if data is not None or path == "finish" else "GET",
+            headers={"x-batchgrid-token": self.token, "Content-Type": "application/json"},
+        )
+        with urllib.request.urlopen(request, timeout=10) as response:
+            return response.read()
+
+    def connect(self) -> None:
+        self.stream = urllib.request.urlopen(f"{self.base}/__batchgrid/events?token={self.token}", timeout=10)
+
+    def run_classification(self, sheet_csv: str, rows: int, columns: List[str]) -> None:
+        plan = {"title": "Classify", "intent": "Label", "sourceColumns": ["review"], "steps": [], "output": {"format": "csv"}}
+        summary = {"status": "done", "total": rows, "success": rows, "failed": 0, "tokens": {"input": 1, "output": 1}, "durationMs": 5}
+        self.call("log", {"entries": [{"id": "u1", "kind": "user", "text": "classify each review", "at": 0}]})
+        self.call("log", {"entries": [{"id": "p1", "kind": "plan", "plan": plan}], "plan": {"costFormatted": "~$0.01", "cost": None, "rows": rows, "missingSecrets": []}})
+        self.call("log", {"progress": {"completed": 1, "total": rows, "failed": 0, "elapsed": 100}})
+        self.call("log", {"entries": [{"id": "r1", "kind": "run", "plan": plan, "summary": summary}]})
+        self.call("sheet", {"csv": sheet_csv, "rows": rows, "columns": columns})
+
+
+def open_tab(act) -> Any:
+    """An on_event hook that opens a fake tab once the link is printed, then runs `act` on it"""
+
+    def on_event(event: Dict[str, Any]) -> None:
+        if event["type"] == "ui":
+            tab = FakeTab(event["url"])
+            tab.connect()
+            threading.Thread(target=act, args=(tab,), daemon=True).start()
+
+    return on_event
+
+
+def test_the_sheet_comes_back_with_new_columns_and_edits(capsys: pytest.CaptureFixture[str]) -> None:
+    df = pd.DataFrame({"review": ["Great", "Bad", "Okay"], "stars": [5, 1, 3], "note": ["a", "b", "c"]}, index=["x", "y", "z"])
+
+    def act(tab: FakeTab) -> None:
+        # The run added a column, and the user fixed a note by hand
+        tab.run_classification(
+            "review,stars,note,sentiment\nGreat,5,a,positive\nBad,1,B!,negative\nOkay,3,c,positive\n",
+            3,
+            ["review", "stars", "note", "sentiment"],
+        )
+        tab.call("finish", {})
+
+    result = batchgrid.ui(df, open_browser=False, on_event=open_tab(act))
+
+    assert result is not None
+    assert list(result.columns) == ["review", "stars", "note", "sentiment"]
+    assert list(result.index) == ["x", "y", "z"]
+    assert result["stars"].dtype == df["stars"].dtype
+    assert result.loc["y", "note"] == "B!"
+    assert result.loc["y", "sentiment"] == "negative"
+
+    printed = capsys.readouterr().out
+    assert "batchgrid is open at http://127.0.0.1:" in printed
+    assert "❯ classify each review" in printed
+    assert "~$0.01" in printed
+    assert "✔ 3/3 rows, 0 failed" in printed
+    assert "Sheet synced: 3 rows × 4 columns" in printed
+    assert "Finished in the browser." in printed
+
+
+def test_closing_the_tab_returns_what_it_last_synced(reviews_csv: Path) -> None:
+    def act(tab: FakeTab) -> None:
+        tab.call("sheet", {"csv": "review,len\nGreat product,13\n", "rows": 1, "columns": ["review", "len"]})
+        tab.stream.close()
+
+    result = batchgrid.ui(reviews_csv, open_browser=False, log=False, on_event=open_tab(act))
+
+    # A file in, a sheet out - as shown, since the tab reshaped it
+    assert result is not None
+    assert result.to_dict("records") == [{"review": "Great product", "len": "13"}]
+
+
+@pytest.mark.skipif(sys.platform == "win32", reason="SIGINT forwarding is POSIX-only")
+def test_interrupting_the_cell_returns_instead_of_raising() -> None:
+    df = pd.DataFrame({"review": ["Great"]})
+
+    def act(tab: FakeTab) -> None:
+        tab.call("sheet", {"csv": "review,sentiment\nGreat,positive\n", "rows": 1, "columns": ["review", "sentiment"]})
+        time.sleep(0.3)
+        _thread.interrupt_main()
+
+    result = batchgrid.ui(df, open_browser=False, log=False, on_event=open_tab(act))
+
+    assert result is not None
+    assert result.loc[0, "sentiment"] == "positive"
+
+
+def test_in_a_notebook_the_workspace_shows_in_the_cell(monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]) -> None:
+    shown: List[Any] = []
+
+    class Handle:
+        def update(self, obj: Any) -> None:
+            shown.append(obj)
+
+    def display(obj: Any, display_id: bool = False) -> Handle:
+        shown.append(obj)
+        return Handle()
+
+    # A stand-in for the IPython a Jupyter kernel runs
+    ipython = types.ModuleType("IPython")
+    ipython.get_ipython = lambda: types.SimpleNamespace(config={"IPKernelApp": {}})  # type: ignore[attr-defined]
+    ipython_display = types.ModuleType("IPython.display")
+    ipython_display.HTML = lambda html: html  # type: ignore[attr-defined]
+    ipython_display.IFrame = lambda src, **options: {"src": src, **options}  # type: ignore[attr-defined]
+    ipython_display.display = display  # type: ignore[attr-defined]
+    monkeypatch.setitem(sys.modules, "IPython", ipython)
+    monkeypatch.setitem(sys.modules, "IPython.display", ipython_display)
+
+    urls: List[str] = []
+
+    def act(tab: FakeTab) -> None:
+        urls.append(tab.url)
+        tab.call("finish", {})
+
+    # No open_browser=False: showing it in the cell never opens a tab
+    batchgrid.ui(on_event=open_tab(act))
+
+    assert len(shown) == 2
+    assert shown[0]["src"] == urls[0] and shown[0]["height"] == 720
+    # The server behind it stopped, so a note takes the workspace's place
+    assert "batchgrid closed" in shown[1]
+    printed = capsys.readouterr().out
+    assert "is open at" not in printed
+    assert "Finished." in printed
+
+
+def test_nothing_synced_returns_none() -> None:
+    result = batchgrid.ui(open_browser=False, log=False, on_event=open_tab(lambda tab: tab.call("finish", {})))
+    assert result is None
+
+
+def test_the_pip_command_does_not_find_itself(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    shim_dir, node_dir = tmp_path / "shim", tmp_path / "node"
+    shim_dir.mkdir()
+    node_dir.mkdir()
+    for directory, first_line in ((shim_dir, "#!/usr/bin/env python3"), (node_dir, "#!/usr/bin/env node")):
+        script = directory / "batchgrid"
+        script.write_text(f"{first_line}\n", encoding="utf-8")
+        script.chmod(script.stat().st_mode | stat.S_IEXEC)
+    monkeypatch.setenv("PATH", os.pathsep.join([str(shim_dir), str(node_dir)]))
+
+    assert _node_cli_on_path() == str(node_dir / "batchgrid")
+
+
+def test_a_cli_without_ui_says_so() -> None:
+    # A stand-in for an old CLI: it knows no `ui` command
+    old_cli = [sys.executable, "-c", "import sys; print(\"error: unknown command 'ui'\", file=sys.stderr); sys.exit(1)"]
+    with pytest.raises(batchgrid.BatchgridError) as caught:
+        batchgrid.ui(open_browser=False, log=False, cli=old_cli)
+    assert caught.value.code == "cli_failed"
+    assert "too old" in caught.value.message