labnotes 0.0.15__tar.gz → 0.0.17__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: labnotes
-Version: 0.0.15
+Version: 0.0.17
 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>
@@ -73,6 +73,7 @@ Each takes `--format table` (the default) or `--format json`.
 experiments folder:
 
 ```toml
+name = "Model and effort"
 command = "uv run scripts/study.py --output {run_dir}"
 repeats = 5
 
@@ -81,6 +82,9 @@ model = ["opus", "sonnet"]
 effort = ["low", "high"]
 ```
 
+`name` is optional: a display name for the experiment, shown in the live view
+and as `display_name` in `experiments`. The folder name stays the key, so
+renaming the experiment means editing `name`.
 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
@@ -98,7 +102,8 @@ 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.
+  kills them. Closing the terminal or sending SIGTERM stops them the same way,
+  then kills any still going 5 seconds later.
 - A second `run` of the same experiment fails while the first holds the lock.
 - It exits 1 if any run failed.
 

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

@@ -50,6 +50,7 @@ Each takes `--format table` (the default) or `--format json`.
 experiments folder:
 
 ```toml
+name = "Model and effort"
 command = "uv run scripts/study.py --output {run_dir}"
 repeats = 5
 
@@ -58,6 +59,9 @@ model = ["opus", "sonnet"]
 effort = ["low", "high"]
 ```
 
+`name` is optional: a display name for the experiment, shown in the live view
+and as `display_name` in `experiments`. The folder name stays the key, so
+renaming the experiment means editing `name`.
 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
@@ -75,7 +79,8 @@ 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.
+  kills them. Closing the terminal or sending SIGTERM stops them the same way,
+  then kills any still going 5 seconds later.
 - A second `run` of the same experiment fails while the first holds the lock.
 - It exits 1 if any run failed.
 

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

@@ -40,6 +40,7 @@ Each takes `--format table` (the default) or `--format json`; use `--format json
 experiments folder:
 
 ```toml
+name = "Model and effort"
 command = "uv run scripts/study.py --output {run_dir}"
 repeats = 5
 
@@ -48,6 +49,9 @@ model = ["opus", "sonnet"]
 effort = ["low", "high"]
 ```
 
+`name` is optional: a display name for the experiment, shown in the live view
+and as `display_name` in `experiments`. The folder name stays the key, so
+renaming the experiment means editing `name`.
 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
@@ -58,6 +62,14 @@ Each param is appended as `--name value`, with the name as written (use
 and tables as JSON. labnotes writes `run.json` (params, created, ended, exit
 code), `stdout.log` and `stderr.log` to the run folder.
 
+A script run by labnotes should:
+
+- take each param as a `--name value` flag, parsing lists and tables from JSON;
+- take its output folder as an argument, passed in `command` as `{run_dir}`, and write everything it produces there;
+- exit non-zero when it fails, so the run counts as failed and runs again next time.
+
+Runs can take a long time. Start `run` in the background, then check on it with `labnotes experiments foo runs`; a run with no `ended` is still going.
+
 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.
@@ -65,7 +77,8 @@ 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.
+  kills them. Closing the terminal or sending SIGTERM stops them the same way,
+  then kills any still going 5 seconds later.
 - A second `run` of the same experiment fails while the first holds the lock.
 - It exits 1 if any run failed.
 

{labnotes-0.0.15 → labnotes-0.0.17}/src/labnotes/experiments.py

@@ -1,6 +1,5 @@
 import asyncio
 import sys
-from functools import partial
 from pathlib import Path
 
 import click
@@ -60,7 +59,7 @@ def experiments(
     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
+            drive = run_tui if live else lambda start, title: run_headless(start)
             try:
                 results = start_experiment(
                     config, name, experiment_config, concurrency, drive

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

@@ -30,3 +30,4 @@ class ExperimentConfig:
     command: str
     repeats: int
     params: dict[str, list[object]]
+    name: str | None = None

{labnotes-0.0.15 → labnotes-0.0.17}/src/labnotes/runner/read_experiment_config.py

@@ -4,7 +4,7 @@ from pathlib import Path
 
 from labnotes.models import ExperimentConfig
 
-SETTINGS = {"command", "repeats", "params"}
+SETTINGS = {"name", "command", "repeats", "params"}
 
 
 def read_experiment_config(path: Path) -> ExperimentConfig:
@@ -16,6 +16,9 @@ def read_experiment_config(path: Path) -> ExperimentConfig:
     unknown = sorted(values.keys() - SETTINGS)
     if unknown:
         raise ValueError(f"{path}: unknown keys {', '.join(unknown)}")
+    name = values.get("name")
+    if name is not None and (not isinstance(name, str) or not name.strip()):
+        raise ValueError(f"{path}: name must be a string")
     command = values.get("command")
     if not isinstance(command, str) or not command.strip():
         raise ValueError(f"{path}: command must be a string")
@@ -25,11 +28,11 @@ def read_experiment_config(path: Path) -> ExperimentConfig:
     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():
+    for param, options in params.items():
         if not isinstance(options, list) or not options:
-            raise ValueError(f"{path}: params.{name} must be a non-empty list")
+            raise ValueError(f"{path}: params.{param} 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)
+    return ExperimentConfig(command, repeats, params, name)

{labnotes-0.0.15 → labnotes-0.0.17}/src/labnotes/runner/run_experiment.py

@@ -38,13 +38,13 @@ async def run_experiment(
     def interrupt() -> None:
         nonlocal stopping
         plan.clear()
-        if stopping:
-            report({"event": "killing"})
-            signal_runs(signal.SIGKILL)
-        else:
+        if not stopping:
             stopping = True
             report({"event": "stopping"})
             signal_runs(signal.SIGTERM)
+        elif running:
+            report({"event": "killing"})
+            signal_runs(signal.SIGKILL)
 
     async def work() -> None:
         while plan:

{labnotes-0.0.15 → labnotes-0.0.17}/src/labnotes/runner/run_headless.py

@@ -6,10 +6,12 @@ import click
 
 from labnotes.models import Start
 from labnotes.runner.describe_event import describe_event
+from labnotes.runner.stop_then_kill import stop_then_kill
 
 
 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)
+        stop_then_kill(interrupt, signal.SIGTERM, signal.SIGHUP)
 
     return asyncio.run(start(lambda event: click.echo(describe_event(event)), listen))

{labnotes-0.0.15 → labnotes-0.0.17}/src/labnotes/runner/start_experiment.py

@@ -15,7 +15,7 @@ def start_experiment(
     name: str,
     experiment_config: Path | None,
     concurrency: int,
-    drive: Callable[[Start], list[dict[str, object]]],
+    drive: Callable[[Start, str], list[dict[str, object]]],
 ) -> list[dict[str, object]]:
     if experiment_config is None:
         folder = config.experiments.replace("{experiment}", name)
@@ -27,6 +27,7 @@ def start_experiment(
     lock.parent.mkdir(parents=True, exist_ok=True)
     try:
         with FileLock(lock, blocking=False):
-            return drive(partial(run_experiment, config, name, experiment, concurrency))
+            start = partial(run_experiment, config, name, experiment, concurrency)
+            return drive(start, experiment.name or name)
     except Timeout as error:
         raise ValueError(f"{name} is already running ({lock} is held).") from error

labnotes-0.0.17/src/labnotes/runner/stop_then_kill.py

@@ -0,0 +1,15 @@
+import asyncio
+from collections.abc import Callable
+
+GRACE_SECONDS = 5
+
+
+def stop_then_kill(interrupt: Callable[[], None], *signals: int) -> None:
+    loop = asyncio.get_running_loop()
+
+    def stop() -> None:
+        interrupt()
+        loop.call_later(GRACE_SECONDS, interrupt)
+
+    for signal_number in signals:
+        loop.add_signal_handler(signal_number, stop)

{labnotes-0.0.15 → labnotes-0.0.17}/src/labnotes/tables/open_tables.py

@@ -12,7 +12,10 @@ from labnotes.tables.read_run import read_run
 EXPERIMENTS = """
 CREATE TABLE experiment_configs (experiment TEXT PRIMARY KEY, config TEXT);
 CREATE VIEW experiments AS
-  SELECT names.name, experiment_configs.config
+  SELECT
+    names.name,
+    coalesce(experiment_configs.config ->> 'name', names.name) AS display_name,
+    experiment_configs.config
   FROM (
     SELECT experiment AS name FROM experiment_configs
     UNION SELECT experiment FROM files

{labnotes-0.0.15 → labnotes-0.0.17}/src/labnotes/tables/summarize_experiments.py

@@ -4,7 +4,8 @@ from labnotes.sql_quote import quote_string
 
 SUMMARY = """
 SELECT
-  e.name,{config}
+  e.name,
+  e.display_name,{config}
   (SELECT max(created) FROM runs WHERE runs.experiment = e.name) AS last_run,
   (
     SELECT min(t) FROM (

{labnotes-0.0.15 → labnotes-0.0.17}/src/labnotes/tui/run_app.py

@@ -1,3 +1,4 @@
+import signal
 import time
 from collections.abc import Callable
 
@@ -7,6 +8,7 @@ from textual.widgets import DataTable, Footer, Header, Static
 
 from labnotes.models import Start
 from labnotes.runner.describe_event import describe_event
+from labnotes.runner.stop_then_kill import stop_then_kill
 from labnotes.runner.param_args import param_args
 from labnotes.tui.format_elapsed import format_elapsed
 
@@ -50,6 +52,7 @@ class RunApp(App[None]):
 
     def listen(self, interrupt: Callable[[], None]) -> None:
         self.interrupt = interrupt
+        stop_then_kill(interrupt, signal.SIGTERM, signal.SIGHUP)
 
     def show_event(self, event: dict[str, object]) -> None:
         table = self.query_one(DataTable)