labnotes 0.0.14__tar.gz → 0.0.15__tar.gz

{labnotes-0.0.14 → labnotes-0.0.15}/.gitignore

@@ -2,6 +2,7 @@ target/
 node_modules/
 dist/
 coverage/
+.coverage
 *.log
 .DS_Store
 

{labnotes-0.0.14 → labnotes-0.0.15}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: labnotes
-Version: 0.0.14
+Version: 0.0.15
 Summary: Browse experiment designs, notes, and run data from a folder.
 Project-URL: Repository, https://github.com/thekevinscott/labnotes
 Author-email: Kevin Scott <me@thekevinscott.com>
@@ -8,6 +8,8 @@ License-Expression: MIT
 Requires-Python: >=3.12
 Requires-Dist: click>=8.5.0
 Requires-Dist: dirsql>=0.4.110
+Requires-Dist: filelock>=4.2.0
+Requires-Dist: haikunator>=2.1.0
 Requires-Dist: ipykernel>=7.4.0
 Requires-Dist: jinja2>=3.1.6
 Requires-Dist: jupyter-client>=8.10.0
@@ -15,6 +17,7 @@ Requires-Dist: markdown-it-py>=4.2.0
 Requires-Dist: pyyaml>=6.0.3
 Requires-Dist: rich>=14
 Requires-Dist: starlette>=1.8.0
+Requires-Dist: textual>=8.2.8
 Requires-Dist: uvicorn>=0.54.0
 Description-Content-Type: text/markdown
 
@@ -66,6 +69,39 @@ labnotes experiments foo runs   # foo's runs, oldest first
 
 Each takes `--format table` (the default) or `--format json`.
 
+`labnotes experiments foo run` runs `foo` from its `experiment.toml`, in the
+experiments folder:
+
+```toml
+command = "uv run scripts/study.py --output {run_dir}"
+repeats = 5
+
+[params]
+model = ["opus", "sonnet"]
+effort = ["low", "high"]
+```
+
+Each combination of `[params]` runs `repeats` times, round-robin. Only runs
+that exit 0 count, so running again fills in what failed or never ran.
+Each run gets a new run folder. `command` runs in a shell from the root, with
+`{run_dir}` replaced by the run folder's absolute path. Pass it to the
+script so it writes its outputs there.
+Each param is appended as `--name value`, with the name as written (use
+`source-language` for a `--source-language` flag), booleans as 0 or 1, and lists
+and tables as JSON. labnotes writes `run.json` (params, created, ended, exit
+code), `stdout.log` and `stderr.log` to the run folder.
+
+In a terminal, `run` shows a live table of runs (status and time) and stays
+open when they finish; `q` quits. Elsewhere, or with `--no-tui`, it prints a
+line per event instead.
+
+- `--concurrency N` runs N at a time (default 1).
+- `-e PATH` reads another file instead of `experiment.toml`.
+- Ctrl-C stops the running scripts and records their end. A second Ctrl-C
+  kills them.
+- A second `run` of the same experiment fails while the first holds the lock.
+- It exits 1 if any run failed.
+
 `labnotes server` doesn't read `.labnotes.toml` yet. Give it the two folders
 it uses with `--experiments-folder` and `--data-folder`:
 

{labnotes-0.0.14 → labnotes-0.0.15}/README.md

@@ -46,6 +46,39 @@ labnotes experiments foo runs   # foo's runs, oldest first
 
 Each takes `--format table` (the default) or `--format json`.
 
+`labnotes experiments foo run` runs `foo` from its `experiment.toml`, in the
+experiments folder:
+
+```toml
+command = "uv run scripts/study.py --output {run_dir}"
+repeats = 5
+
+[params]
+model = ["opus", "sonnet"]
+effort = ["low", "high"]
+```
+
+Each combination of `[params]` runs `repeats` times, round-robin. Only runs
+that exit 0 count, so running again fills in what failed or never ran.
+Each run gets a new run folder. `command` runs in a shell from the root, with
+`{run_dir}` replaced by the run folder's absolute path. Pass it to the
+script so it writes its outputs there.
+Each param is appended as `--name value`, with the name as written (use
+`source-language` for a `--source-language` flag), booleans as 0 or 1, and lists
+and tables as JSON. labnotes writes `run.json` (params, created, ended, exit
+code), `stdout.log` and `stderr.log` to the run folder.
+
+In a terminal, `run` shows a live table of runs (status and time) and stays
+open when they finish; `q` quits. Elsewhere, or with `--no-tui`, it prints a
+line per event instead.
+
+- `--concurrency N` runs N at a time (default 1).
+- `-e PATH` reads another file instead of `experiment.toml`.
+- Ctrl-C stops the running scripts and records their end. A second Ctrl-C
+  kills them.
+- A second `run` of the same experiment fails while the first holds the lock.
+- It exits 1 if any run failed.
+
 `labnotes server` doesn't read `.labnotes.toml` yet. Give it the two folders
 it uses with `--experiments-folder` and `--data-folder`:
 

{labnotes-0.0.14 → labnotes-0.0.15}/pyproject.toml

@@ -13,6 +13,8 @@ authors = [{ name = "Kevin Scott", email = "me@thekevinscott.com" }]
 dependencies = [
     "click>=8.5.0",
     "dirsql>=0.4.110",
+    "filelock>=4.2.0",
+    "haikunator>=2.1.0",
     "ipykernel>=7.4.0",
     "jinja2>=3.1.6",
     "jupyter-client>=8.10.0",
@@ -20,6 +22,7 @@ dependencies = [
     "pyyaml>=6.0.3",
     "rich>=14",
     "starlette>=1.8.0",
+    "textual>=8.2.8",
     "uvicorn>=0.54.0",
 ]
 
@@ -62,3 +65,8 @@ select = ["E4", "E7", "E9", "F", "TID252"]
 
 [tool.ruff.lint.flake8-tidy-imports]
 ban-relative-imports = "all"
+
+# haikunator ships no type hints.
+[[tool.mypy.overrides]]
+module = ["haikunator"]
+ignore_missing_imports = true

{labnotes-0.0.14 → labnotes-0.0.15}/src/labnotes/context.md

@@ -36,6 +36,39 @@ labnotes experiments foo runs   # foo's runs, oldest first
 
 Each takes `--format table` (the default) or `--format json`; use `--format json` when you parse the output.
 
+`labnotes experiments foo run` runs `foo` from its `experiment.toml`, in the
+experiments folder:
+
+```toml
+command = "uv run scripts/study.py --output {run_dir}"
+repeats = 5
+
+[params]
+model = ["opus", "sonnet"]
+effort = ["low", "high"]
+```
+
+Each combination of `[params]` runs `repeats` times, round-robin. Only runs
+that exit 0 count, so running again fills in what failed or never ran.
+Each run gets a new run folder. `command` runs in a shell from the root, with
+`{run_dir}` replaced by the run folder's absolute path. Pass it to the
+script so it writes its outputs there.
+Each param is appended as `--name value`, with the name as written (use
+`source-language` for a `--source-language` flag), booleans as 0 or 1, and lists
+and tables as JSON. labnotes writes `run.json` (params, created, ended, exit
+code), `stdout.log` and `stderr.log` to the run folder.
+
+In a terminal, `run` shows a live table of runs (status and time) and stays
+open when they finish; `q` quits. Elsewhere, or with `--no-tui`, it prints a
+line per event instead.
+
+- `--concurrency N` runs N at a time (default 1).
+- `-e PATH` reads another file instead of `experiment.toml`.
+- Ctrl-C stops the running scripts and records their end. A second Ctrl-C
+  kills them.
+- A second `run` of the same experiment fails while the first holds the lock.
+- It exits 1 if any run failed.
+
 `labnotes server` doesn't read `.labnotes.toml` yet: pass `--experiments-folder` and `--data-folder`, or set `LABNOTES_EXPERIMENTS_FOLDER` and `LABNOTES_DATA_FOLDER`. The experiments folder has one subfolder per experiment, each with a `design.yaml` and markdown notes. The data folder holds run data and a `.dirsql.toml` declaring a `runs` table with a `study` column.
 
 The run data lives in the data folder. Query it with [dirsql](https://dirsql.dev) and the data folder's `.dirsql.toml`, which declares the `runs` table:

labnotes-0.0.15/src/labnotes/experiments.py

@@ -0,0 +1,76 @@
+import asyncio
+import sys
+from functools import partial
+from pathlib import Path
+
+import click
+
+from labnotes.load_config import load_config
+from labnotes.print_rows import print_rows
+from labnotes.read_config import CONFIG_FILE
+from labnotes.runner.run_headless import run_headless
+from labnotes.runner.start_experiment import start_experiment
+from labnotes.tables.experiment_rows import experiment_rows
+from labnotes.tui.run_tui import run_tui
+
+
+@click.command(help="List experiments, show one, list its runs, or run it.")
+@click.argument("name", required=False)
+@click.argument("action", required=False, type=click.Choice(["runs", "run"]))
+@click.option(
+    "--format",
+    "output_format",
+    type=click.Choice(["table", "json"]),
+    default="table",
+    show_default=True,
+)
+@click.option(
+    "--concurrency",
+    type=click.IntRange(min=1),
+    default=1,
+    show_default=True,
+    help="With run: how many runs at once.",
+)
+@click.option(
+    "-e",
+    "--experiment-config",
+    type=click.Path(exists=True, dir_okay=False, path_type=Path),
+    help="With run: read this file instead of the experiment's experiment.toml.",
+)
+@click.option(
+    "--no-tui",
+    is_flag=True,
+    help="With run: print a line per event instead of the live view.",
+)
+@click.pass_context
+def experiments(
+    ctx: click.Context,
+    name: str | None,
+    action: str | None,
+    output_format: str,
+    concurrency: int,
+    experiment_config: Path | None,
+    no_tui: bool,
+) -> None:
+    config = load_config(ctx)
+    if config is None:
+        raise click.ClickException(
+            f"No {CONFIG_FILE} here. Run labnotes init, or pass -c PATH."
+        )
+    match name, action:
+        case str(), "run":
+            live = sys.stdout.isatty() and sys.stderr.isatty() and not no_tui
+            drive = partial(run_tui, title=name) if live else run_headless
+            try:
+                results = start_experiment(
+                    config, name, experiment_config, concurrency, drive
+                )
+            except ValueError as error:
+                raise click.ClickException(str(error)) from error
+            failed = sum(result["exit_code"] != 0 for result in results)
+            click.echo(f"{len(results) - failed} passed, {failed} failed.")
+            ctx.exit(1 if failed else 0)
+    rows = asyncio.run(experiment_rows(config, name, action))
+    if rows is None:
+        raise click.ClickException(f"No experiment named {name}.")
+    print_rows(rows, output_format)

{labnotes-0.0.14 → labnotes-0.0.15}/src/labnotes/models.py

@@ -1,5 +1,11 @@
+from collections.abc import Callable, Coroutine
 from dataclasses import dataclass, field
 from pathlib import Path
+from typing import Any
+
+Report = Callable[[dict[str, object]], None]
+Listen = Callable[[Callable[[], None]], None]
+Start = Callable[[Report, Listen], Coroutine[Any, Any, list[dict[str, object]]]]
 
 
 @dataclass(frozen=True)
@@ -17,3 +23,10 @@ class LabnotesConfig:
     experiments: str
     files: str
     runs: str
+
+
+@dataclass(frozen=True)
+class ExperimentConfig:
+    command: str
+    repeats: int
+    params: dict[str, list[object]]

labnotes-0.0.15/src/labnotes/runner/describe_event.py

@@ -0,0 +1,17 @@
+from labnotes.runner.param_args import param_args
+
+
+def describe_event(event: dict[str, object]) -> str:
+    match event["event"]:
+        case "planned":
+            return f"{event['runs']} runs to go, {event['concurrency']} at a time."
+        case "started":
+            args = " ".join(param_args(event["params"]))  # type: ignore[arg-type]
+            return f"{event['run']} started {args}".rstrip()
+        case "ended":
+            outcome = event["error"] or f"exited {event['exit_code']}"
+            return f"{event['run']} {outcome}"
+        case "stopping":
+            return "Stopping runs. Ctrl-C again to kill them."
+        case _:
+            return "Killing runs."

labnotes-0.0.15/src/labnotes/runner/execute_run.py

@@ -0,0 +1,49 @@
+import asyncio
+import time
+from pathlib import Path
+
+from labnotes.runner.shell_command import shell_command
+from labnotes.runner.write_run_json import write_run_json
+from labnotes.tables.iso_time import iso_time
+
+
+async def execute_run(
+    root: Path,
+    folder: Path,
+    command: str,
+    params: dict[str, object],
+    running: set[asyncio.subprocess.Process],
+) -> dict[str, object]:
+    run: dict[str, object] = {
+        "params": params,
+        "created": iso_time(time.time()),
+        "ended": None,
+        "exit_code": None,
+        "error": None,
+    }
+    write_run_json(folder, run)
+    with (
+        (folder / "stdout.log").open("wb") as stdout,
+        (folder / "stderr.log").open("wb") as stderr,
+    ):
+        try:
+            process = await asyncio.create_subprocess_shell(
+                shell_command(command, folder, params),
+                cwd=root,
+                stdout=stdout,
+                stderr=stderr,
+                # Own process group, so Ctrl-C reaches labnotes first and the
+                # runner decides how each run stops.
+                start_new_session=True,
+            )
+        except OSError as error:
+            run["error"] = str(error)
+        else:
+            running.add(process)
+            try:
+                run["exit_code"] = await process.wait()
+            finally:
+                running.discard(process)
+    run["ended"] = iso_time(time.time())
+    write_run_json(folder, run)
+    return run

labnotes-0.0.15/src/labnotes/runner/lock_path.py

@@ -0,0 +1,7 @@
+import posixpath
+from pathlib import Path
+
+
+def lock_path(root: Path, template: str, experiment: str) -> Path:
+    head = template.replace("{experiment}", experiment).split("{run}")[0]
+    return root / posixpath.dirname(head) / ".labnotes.lock"

labnotes-0.0.15/src/labnotes/runner/new_run_id.py

@@ -0,0 +1,11 @@
+from collections.abc import Callable
+
+from haikunator import Haikunator
+
+
+def new_run_id(taken: Callable[[str], bool]) -> str:
+    name = Haikunator().haikunate(token_length=0)
+    candidate, suffix = name, 2
+    while taken(candidate):
+        candidate, suffix = f"{name}-{suffix}", suffix + 1
+    return candidate

labnotes-0.0.15/src/labnotes/runner/param_args.py

@@ -0,0 +1,16 @@
+import json
+
+
+def param_args(params: dict[str, object]) -> list[str]:
+    args: list[str] = []
+    for name, value in params.items():
+        if isinstance(value, bool):
+            text = "1" if value else "0"
+        elif isinstance(value, str):
+            text = value
+        elif isinstance(value, list | dict):
+            text = json.dumps(value)
+        else:
+            text = str(value)
+        args += [f"--{name}", text]
+    return args

labnotes-0.0.15/src/labnotes/runner/param_grid.py

@@ -0,0 +1,6 @@
+from itertools import product
+
+
+def param_grid(params: dict[str, list[object]]) -> list[dict[str, object]]:
+    choices = ([(name, value) for value in values] for name, values in params.items())
+    return [dict(cell) for cell in product(*choices)]

labnotes-0.0.15/src/labnotes/runner/plan_runs.py

@@ -0,0 +1,9 @@
+def plan_runs(
+    cells: list[dict[str, object]], repeats: int, finished: list[dict[str, object]]
+) -> list[dict[str, object]]:
+    return [
+        cell
+        for round_ in range(repeats)
+        for cell in cells
+        if round_ < repeats - finished.count(cell)
+    ]

labnotes-0.0.15/src/labnotes/runner/read_experiment_config.py

@@ -0,0 +1,35 @@
+import json
+import tomllib
+from pathlib import Path
+
+from labnotes.models import ExperimentConfig
+
+SETTINGS = {"command", "repeats", "params"}
+
+
+def read_experiment_config(path: Path) -> ExperimentConfig:
+    try:
+        with path.open("rb") as file:
+            values = tomllib.load(file)
+    except tomllib.TOMLDecodeError as error:
+        raise ValueError(f"{path}: {error}") from error
+    unknown = sorted(values.keys() - SETTINGS)
+    if unknown:
+        raise ValueError(f"{path}: unknown keys {', '.join(unknown)}")
+    command = values.get("command")
+    if not isinstance(command, str) or not command.strip():
+        raise ValueError(f"{path}: command must be a string")
+    repeats = values.get("repeats", 1)
+    if isinstance(repeats, bool) or not isinstance(repeats, int) or repeats < 1:
+        raise ValueError(f"{path}: repeats must be a positive integer")
+    params = values.get("params", {})
+    if not isinstance(params, dict):
+        raise ValueError(f"{path}: params must be a table, like [params]")
+    for name, options in params.items():
+        if not isinstance(options, list) or not options:
+            raise ValueError(f"{path}: params.{name} must be a non-empty list")
+    try:
+        json.dumps(params)
+    except TypeError as error:
+        raise ValueError(f"{path}: params can't hold dates or times") from error
+    return ExperimentConfig(command, repeats, params)

labnotes-0.0.15/src/labnotes/runner/run_experiment.py

@@ -0,0 +1,66 @@
+import asyncio
+import contextlib
+import json
+import os
+import signal
+
+from labnotes.models import ExperimentConfig, LabnotesConfig, Listen, Report
+from labnotes.runner.execute_run import execute_run
+from labnotes.runner.new_run_id import new_run_id
+from labnotes.runner.param_grid import param_grid
+from labnotes.runner.plan_runs import plan_runs
+from labnotes.runner.run_folder import run_folder
+from labnotes.tables.list_experiment_runs import list_experiment_runs
+from labnotes.tables.open_tables import open_tables
+
+
+async def run_experiment(
+    config: LabnotesConfig,
+    name: str,
+    experiment: ExperimentConfig,
+    concurrency: int,
+    report: Report,
+    listen: Listen,
+) -> list[dict[str, object]]:
+    runs = await list_experiment_runs(open_tables(config), name)
+    finished = [json.loads(str(run["params"])) for run in runs if run["exit_code"] == 0]
+    plan = plan_runs(param_grid(experiment.params), experiment.repeats, finished)
+    report({"event": "planned", "runs": len(plan), "concurrency": concurrency})
+    running: set[asyncio.subprocess.Process] = set()
+    results: list[dict[str, object]] = []
+    stopping = False
+
+    def signal_runs(signal_number: int) -> None:
+        for process in running:
+            with contextlib.suppress(ProcessLookupError):
+                os.killpg(process.pid, signal_number)
+
+    def interrupt() -> None:
+        nonlocal stopping
+        plan.clear()
+        if stopping:
+            report({"event": "killing"})
+            signal_runs(signal.SIGKILL)
+        else:
+            stopping = True
+            report({"event": "stopping"})
+            signal_runs(signal.SIGTERM)
+
+    async def work() -> None:
+        while plan:
+            params = plan.pop(0)
+            run = new_run_id(
+                lambda id_: run_folder(config.root, config.runs, name, id_).exists()
+            )
+            folder = run_folder(config.root, config.runs, name, run)
+            folder.mkdir(parents=True)
+            report({"event": "started", "run": run, "params": params})
+            result = await execute_run(
+                config.root, folder, experiment.command, params, running
+            )
+            report({"event": "ended", "run": run, **result})
+            results.append(result)
+
+    listen(interrupt)
+    await asyncio.gather(*(work() for _ in range(concurrency)))
+    return results

labnotes-0.0.15/src/labnotes/runner/run_folder.py

@@ -0,0 +1,5 @@
+from pathlib import Path
+
+
+def run_folder(root: Path, template: str, experiment: str, run: str) -> Path:
+    return root / template.replace("{experiment}", experiment).replace("{run}", run)

labnotes-0.0.15/src/labnotes/runner/run_headless.py

@@ -0,0 +1,15 @@
+import asyncio
+import signal
+from collections.abc import Callable
+
+import click
+
+from labnotes.models import Start
+from labnotes.runner.describe_event import describe_event
+
+
+def run_headless(start: Start) -> list[dict[str, object]]:
+    def listen(interrupt: Callable[[], None]) -> None:
+        asyncio.get_running_loop().add_signal_handler(signal.SIGINT, interrupt)
+
+    return asyncio.run(start(lambda event: click.echo(describe_event(event)), listen))

labnotes-0.0.15/src/labnotes/runner/shell_command.py

@@ -0,0 +1,9 @@
+import shlex
+from pathlib import Path
+
+from labnotes.runner.param_args import param_args
+
+
+def shell_command(command: str, folder: Path, params: dict[str, object]) -> str:
+    filled = command.replace("{run_dir}", shlex.quote(str(folder)))
+    return f"{filled} {shlex.join(param_args(params))}".rstrip()

labnotes-0.0.15/src/labnotes/runner/start_experiment.py

@@ -0,0 +1,32 @@
+from collections.abc import Callable
+from functools import partial
+from pathlib import Path
+
+from filelock import FileLock, Timeout
+
+from labnotes.models import LabnotesConfig, Start
+from labnotes.runner.lock_path import lock_path
+from labnotes.runner.read_experiment_config import read_experiment_config
+from labnotes.runner.run_experiment import run_experiment
+
+
+def start_experiment(
+    config: LabnotesConfig,
+    name: str,
+    experiment_config: Path | None,
+    concurrency: int,
+    drive: Callable[[Start], list[dict[str, object]]],
+) -> list[dict[str, object]]:
+    if experiment_config is None:
+        folder = config.experiments.replace("{experiment}", name)
+        experiment_config = config.root / folder / "experiment.toml"
+    if not experiment_config.is_file():
+        raise ValueError(f"No experiment.toml for {name} at {experiment_config}.")
+    experiment = read_experiment_config(experiment_config)
+    lock = lock_path(config.root, config.runs, name)
+    lock.parent.mkdir(parents=True, exist_ok=True)
+    try:
+        with FileLock(lock, blocking=False):
+            return drive(partial(run_experiment, config, name, experiment, concurrency))
+    except Timeout as error:
+        raise ValueError(f"{name} is already running ({lock} is held).") from error

labnotes-0.0.15/src/labnotes/runner/write_run_json.py

@@ -0,0 +1,8 @@
+import json
+from pathlib import Path
+
+
+def write_run_json(folder: Path, run: dict[str, object]) -> None:
+    partial = folder / "run.json.tmp"
+    partial.write_text(json.dumps(run, indent=2) + "\n", encoding="utf-8")
+    partial.replace(folder / "run.json")

labnotes-0.0.15/src/labnotes/tui/format_elapsed.py

@@ -0,0 +1,8 @@
+def format_elapsed(seconds: float) -> str:
+    minutes, rest = divmod(int(seconds), 60)
+    hours, minutes = divmod(minutes, 60)
+    if hours:
+        return f"{hours}h {minutes:02}m"
+    if minutes:
+        return f"{minutes}m {rest:02}s"
+    return f"{rest}s"

labnotes-0.0.15/src/labnotes/tui/run_app.py

@@ -0,0 +1,90 @@
+import time
+from collections.abc import Callable
+
+from textual.app import App, ComposeResult
+from textual.binding import Binding
+from textual.widgets import DataTable, Footer, Header, Static
+
+from labnotes.models import Start
+from labnotes.runner.describe_event import describe_event
+from labnotes.runner.param_args import param_args
+from labnotes.tui.format_elapsed import format_elapsed
+
+
+class RunApp(App[None]):
+    BINDINGS = [
+        Binding("ctrl+c", "interrupt", "Stop runs"),
+        Binding("q", "quit", "Quit"),
+    ]
+
+    def __init__(self, start: Start, title: str) -> None:
+        super().__init__()
+        self.start = start
+        self.title = title
+        self.results: list[dict[str, object]] = []
+        self.interrupt: Callable[[], None] = lambda: None
+        self.done = False
+        self.started: dict[str, float] = {}
+
+    def compose(self) -> ComposeResult:
+        yield Header()
+        yield DataTable(id="runs", cursor_type="none")
+        yield Static(id="status")
+        yield Footer()
+
+    def on_mount(self) -> None:
+        table = self.query_one(DataTable)
+        for column in ("run", "params", "status", "time"):
+            table.add_column(column, key=column)
+
+    def on_ready(self) -> None:
+        self.set_interval(1, self.tick)
+        self.run_worker(self.drive())
+
+    async def drive(self) -> None:
+        self.results = await self.start(self.show_event, self.listen)
+        self.done = True
+        failed = sum(result["exit_code"] != 0 for result in self.results)
+        passed = len(self.results) - failed
+        self.show(f"{passed} passed, {failed} failed. q to quit.")
+
+    def listen(self, interrupt: Callable[[], None]) -> None:
+        self.interrupt = interrupt
+
+    def show_event(self, event: dict[str, object]) -> None:
+        table = self.query_one(DataTable)
+        run = str(event.get("run"))
+        match event["event"]:
+            case "started":
+                self.started[run] = time.monotonic()
+                args = " ".join(param_args(event["params"]))  # type: ignore[arg-type]
+                table.add_row(run, args, "running", "0s", key=run)
+            case "ended":
+                outcome = event["error"] or f"exited {event['exit_code']}"
+                table.update_cell(run, "status", outcome, update_width=True)
+                self.tick()
+                del self.started[run]
+            case _:
+                self.show(describe_event(event))
+
+    def tick(self) -> None:
+        table = self.query_one(DataTable)
+        for run, began in self.started.items():
+            table.update_cell(
+                run, "time", format_elapsed(time.monotonic() - began), update_width=True
+            )
+
+    def show(self, text: str) -> None:
+        self.query_one("#status", Static).update(text)
+
+    def action_interrupt(self) -> None:
+        if self.done:
+            self.exit()
+        else:
+            self.interrupt()
+
+    async def action_quit(self) -> None:
+        if self.done:
+            self.exit()
+        else:
+            self.show("Runs are still going. Ctrl-C stops them.")

labnotes-0.0.15/src/labnotes/tui/run_tui.py

@@ -0,0 +1,8 @@
+from labnotes.models import Start
+from labnotes.tui.run_app import RunApp
+
+
+def run_tui(start: Start, title: str) -> list[dict[str, object]]:
+    app = RunApp(start, title)
+    app.run()
+    return app.results

{labnotes-0.0.14 → labnotes-0.0.15}/uv.lock

@@ -273,6 +273,15 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/4d/dd/8bc67e7d5ffc1d88aa5af511189dfb76dc4e1e5b808fab186146ef2663e5/executing-2.3.0-py3-none-any.whl", hash = "sha256:736e859c9f8701f11fcf516856f26f562e04776387824b43a35a1dfe21c84122", size = 29393, upload-time = "2026-10-10T14:06:02.777Z" },
 ]
 
+[[package]]
+name = "filelock"
+version = "4.2.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/f4/a9/1af41b37c3279712b22cdc63aac78a52432202b6fe1f9666a2a3d2831fb4/filelock-4.2.0.tar.gz", hash = "sha256:7a60906c75227cf04d0c273afadc8219400f11aeb13cc69591d4f6cdc6c8036e", size = 569667, upload-time = "2026-10-14T20:57:13.11Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/8e/a3/9bc26acff301fe1aaea1cc3d82a1d57e0a34df3e1cadbfa91ac2dbcdde5c/filelock-4.2.0-py3-none-any.whl", hash = "sha256:2ff5690882e8cdb00ef31fb3d01a3094c29f30985426c59495afb1733f3b7238", size = 135032, upload-time = "2026-10-14T20:57:11.349Z" },
+]
+
 [[package]]
 name = "h11"
 version = "0.16.0"
@@ -282,6 +291,15 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/04/4b/29cac41a4d98d144bf5f6d33995617b185d14b22401f75ca86f384e87ff1/h11-0.16.0-py3-none-any.whl", hash = "sha256:63cf8bbe7522de3bf65932fda1d9c2772064ffb3dae62d55932da54b31cb6c86", size = 37515, upload-time = "2025-04-24T03:35:24.344Z" },
 ]
 
+[[package]]
+name = "haikunator"
+version = "2.1.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/af/58/6a000ee0ec34cac5c78669359a8b1db969f1f511454a140ad3d193714ba2/haikunator-2.1.0.zip", hash = "sha256:91ee3949a3a613cac037ddde0b16b17062e248376b11491436e49d5ddc75ff9b", size = 4933, upload-time = "2016-09-20T17:36:00.843Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/43/fa/130968f1a1bb1461c287b9ff35c630460801783243acda2cbf3a4c5964a5/haikunator-2.1.0-py2.py3-none-any.whl", hash = "sha256:66f68b15345b279f78a5fffd4ab56cfb19a9dbb1f41b7f442472efd4cb83458e", size = 4595, upload-time = "2016-09-20T17:35:58.142Z" },
+]
+
 [[package]]
 name = "httpcore2"
 version = "2.13.1"
@@ -455,6 +473,8 @@ source = { editable = "." }
 dependencies = [
     { name = "click" },
     { name = "dirsql" },
+    { name = "filelock" },
+    { name = "haikunator" },
     { name = "ipykernel" },
     { name = "jinja2" },
     { name = "jupyter-client" },
@@ -462,6 +482,7 @@ dependencies = [
     { name = "pyyaml" },
     { name = "rich" },
     { name = "starlette" },
+    { name = "textual" },
     { name = "uvicorn" },
 ]
 
@@ -478,6 +499,8 @@ dev = [
 requires-dist = [
     { name = "click", specifier = ">=8.5.0" },
     { name = "dirsql", specifier = ">=0.4.110" },
+    { name = "filelock", specifier = ">=4.2.0" },
+    { name = "haikunator", specifier = ">=2.1.0" },
     { name = "ipykernel", specifier = ">=7.4.0" },
     { name = "jinja2", specifier = ">=3.1.6" },
     { name = "jupyter-client", specifier = ">=8.10.0" },
@@ -485,6 +508,7 @@ requires-dist = [
     { name = "pyyaml", specifier = ">=6.0.3" },
     { name = "rich", specifier = ">=14" },
     { name = "starlette", specifier = ">=1.8.0" },
+    { name = "textual", specifier = ">=8.2.8" },
     { name = "uvicorn", specifier = ">=0.54.0" },
 ]
 
@@ -598,6 +622,15 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/36/69/7a5d10ac409c4da0355e054a14371871da9b5557fcc42772cd00181c6cce/librt-0.16.0-cp315-cp315t-win_arm64.whl", hash = "sha256:8ceafb70f2a4f0826f11031942e59c0728fd98da112dc346d4352bde1e486866", size = 116391, upload-time = "2026-09-29T00:55:07.484Z" },
 ]
 
+[[package]]
+name = "linkify-it-py"
+version = "2.2.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/45/98/7a1a5f31fd5c7ba93e963b168e244b8e3dd705b3d2a718e3c3307583bf57/linkify_it_py-2.2.0.tar.gz", hash = "sha256:907acd2d17ac1fbb9ddb62c8957ccbd6158cac602231a15c3b0cd1e215f03cee", size = 32939, upload-time = "2026-08-29T07:07:08.305Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/13/d4/1152d1c7ab42d8b908be64fd200ddc870dc9d4925e951198702084aa1a7d/linkify_it_py-2.2.0-py3-none-any.whl", hash = "sha256:3adc40eb5af300b2605fcfdb968c24e1d780a90f1f2221af7c15e5111e94d443", size = 21971, upload-time = "2026-08-29T07:07:07.164Z" },
+]
+
 [[package]]
 name = "markdown-it-py"
 version = "4.2.0"
@@ -610,6 +643,11 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/b3/81/4da04ced5a082363ecfa159c010d200ecbd959ae410c10c0264a38cac0f5/markdown_it_py-4.2.0-py3-none-any.whl", hash = "sha256:9f7ebbcd14fe59494226453aed97c1070d83f8d24b6fc3a3bcf9a38092641c4a", size = 91687, upload-time = "2026-05-07T12:08:27.182Z" },
 ]
 
+[package.optional-dependencies]
+linkify = [
+    { name = "linkify-it-py" },
+]
+
 [[package]]
 name = "markupsafe"
 version = "3.0.4"
@@ -735,6 +773,18 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/41/09/5b161152e2d90f7b87f781c2e1267494aef9c32498df793f73ad0a0a494a/matplotlib_inline-0.2.2-py3-none-any.whl", hash = "sha256:3c821cf1c209f59fb2d2d64abbf5b23b67bcb2210d663f9918dd851c6da1fcf6", size = 9534, upload-time = "2026-05-08T17:33:32.055Z" },
 ]
 
+[[package]]
+name = "mdit-py-plugins"
+version = "0.6.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "markdown-it-py" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/59/fc/f8d0863f8862f25602c0404d75568e89fb6b4109804645e5cdfb1be5cf56/mdit_py_plugins-0.6.1.tar.gz", hash = "sha256:a2bca0f039f39dbd35fb74ae1b5f998608c437463371f0ff7f49a19a17a114d0", size = 56114, upload-time = "2026-05-13T09:03:38.91Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/a5/69/6da5581c6a7fede7dc261bf4e67d6adca4196f176b43288b55b3db395b6e/mdit_py_plugins-0.6.1-py3-none-any.whl", hash = "sha256:214c82fb2ac524472ab6a5bcab1de80f73b50443e187f401bfd77efbc7c6481d", size = 66663, upload-time = "2026-05-13T09:03:37.76Z" },
+]
+
 [[package]]
 name = "mdurl"
 version = "0.1.2"
@@ -1145,6 +1195,23 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/c1/b0/5742e4ac7af5eb58ec3470a537a49d7aa507e5539413e504b3a65ef50ba8/starlette-1.8.0-py3-none-any.whl", hash = "sha256:dfdd6b29c26483288088d990eee59631dedadd66ce20d203402a7ca8e3c4656f", size = 79612, upload-time = "2026-10-13T07:54:38.019Z" },
 ]
 
+[[package]]
+name = "textual"
+version = "8.2.8"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "markdown-it-py", extra = ["linkify"] },
+    { name = "mdit-py-plugins" },
+    { name = "platformdirs" },
+    { name = "pygments" },
+    { name = "rich" },
+    { name = "typing-extensions" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/00/21/39a76b01bd5eea82a04baaca7580e105d8c59450df03998345bb2cfb307b/textual-8.2.8.tar.gz", hash = "sha256:3f106a9fbc73e39dd266c9712432087de78a6d644084c7c241d6a25c3169115b", size = 1860502, upload-time = "2026-06-30T06:51:24.495Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/fb/be/35261223d9416a0751cdff1c7b4a6f881387218a12d439fe22fefebc8c04/textual-8.2.8-py3-none-any.whl", hash = "sha256:267375fd402dc8d981457212efa71f0e3365fd17bba144ba9bb3ed7563cb374a", size = 731418, upload-time = "2026-06-30T06:51:26.364Z" },
+]
+
 [[package]]
 name = "tornado"
 version = "6.5.10"

labnotes-0.0.14/src/labnotes/experiments.py

@@ -1,33 +0,0 @@
-import asyncio
-
-import click
-
-from labnotes.load_config import load_config
-from labnotes.print_rows import print_rows
-from labnotes.read_config import CONFIG_FILE
-from labnotes.tables.experiment_rows import experiment_rows
-
-
-@click.command(help="List experiments, show one, or list its runs.")
-@click.argument("name", required=False)
-@click.argument("action", required=False, type=click.Choice(["runs"]))
-@click.option(
-    "--format",
-    "output_format",
-    type=click.Choice(["table", "json"]),
-    default="table",
-    show_default=True,
-)
-@click.pass_context
-def experiments(
-    ctx: click.Context, name: str | None, action: str | None, output_format: str
-) -> None:
-    config = load_config(ctx)
-    if config is None:
-        raise click.ClickException(
-            f"No {CONFIG_FILE} here. Run labnotes init, or pass -c PATH."
-        )
-    rows = asyncio.run(experiment_rows(config, name, action))
-    if rows is None:
-        raise click.ClickException(f"No experiment named {name}.")
-    print_rows(rows, output_format)