labnotes 0.0.16__tar.gz → 0.0.18__tar.gz

{labnotes-0.0.16 → labnotes-0.0.18}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: labnotes
-Version: 0.0.16
+Version: 0.0.18
 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>
@@ -69,10 +69,15 @@ labnotes experiments foo runs   # foo's runs, oldest first
 
 Each takes `--format table` (the default) or `--format json`.
 
+`labnotes experiments new [NAME]` creates an experiment folder with a starter
+`experiment.toml`, picking a random name if you give none. `new` itself can't
+be an experiment name.
+
 `labnotes experiments foo run` runs `foo` from its `experiment.toml`, in the
 experiments folder:
 
 ```toml
+name = "Model and effort"
 command = "uv run scripts/study.py --output {run_dir}"
 repeats = 5
 
@@ -81,6 +86,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

{labnotes-0.0.16 → labnotes-0.0.18}/README.md

@@ -46,10 +46,15 @@ labnotes experiments foo runs   # foo's runs, oldest first
 
 Each takes `--format table` (the default) or `--format json`.
 
+`labnotes experiments new [NAME]` creates an experiment folder with a starter
+`experiment.toml`, picking a random name if you give none. `new` itself can't
+be an experiment name.
+
 `labnotes experiments foo run` runs `foo` from its `experiment.toml`, in the
 experiments folder:
 
 ```toml
+name = "Model and effort"
 command = "uv run scripts/study.py --output {run_dir}"
 repeats = 5
 
@@ -58,6 +63,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

{labnotes-0.0.16 → labnotes-0.0.18}/src/labnotes/context.md

@@ -36,10 +36,15 @@ 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 new [NAME]` creates an experiment folder with a starter
+`experiment.toml`, picking a random name if you give none. `new` itself can't
+be an experiment name.
+
 `labnotes experiments foo run` runs `foo` from its `experiment.toml`, in the
 experiments folder:
 
 ```toml
+name = "Model and effort"
 command = "uv run scripts/study.py --output {run_dir}"
 repeats = 5
 
@@ -48,6 +53,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

labnotes-0.0.18/src/labnotes/create_experiment.py

@@ -0,0 +1,32 @@
+from pathlib import Path
+
+from labnotes.models import LabnotesConfig
+from labnotes.runner.new_run_id import new_run_id
+
+STARTER = """\
+# Runs from the project root. {run_dir} becomes the run's folder.
+command = "uv run script.py --output {run_dir}"
+repeats = 1
+
+# Each combination runs `repeats` times, passed as --name value.
+[params]
+# model = ["opus", "sonnet"]
+"""
+
+
+def create_experiment(config: LabnotesConfig, name: str | None) -> Path:
+    def folder(candidate: str) -> Path:
+        return config.root / config.experiments.replace("{experiment}", candidate)
+
+    if name is None:
+        name = new_run_id(lambda candidate: folder(candidate).exists())
+    if name == "new":
+        raise ValueError("new is reserved; pick another name.")
+    if "/" in name or name.startswith("."):
+        raise ValueError(f"{name} can't be an experiment name.")
+    path = folder(name)
+    if path.exists():
+        raise ValueError(f"{name} already exists at {path}.")
+    path.mkdir(parents=True)
+    (path / "experiment.toml").write_text(STARTER, encoding="utf-8")
+    return path

{labnotes-0.0.16 → labnotes-0.0.18}/src/labnotes/experiments.py

@@ -1,10 +1,10 @@
 import asyncio
 import sys
-from functools import partial
 from pathlib import Path
 
 import click
 
+from labnotes.create_experiment import create_experiment
 from labnotes.load_config import load_config
 from labnotes.print_rows import print_rows
 from labnotes.read_config import CONFIG_FILE
@@ -14,9 +14,12 @@ 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.command(
+    help="List experiments, show one, list its runs, or run it."
+    " `new [NAME]` creates one."
+)
 @click.argument("name", required=False)
-@click.argument("action", required=False, type=click.Choice(["runs", "run"]))
+@click.argument("action", required=False, metavar="[runs|run]")
 @click.option(
     "--format",
     "output_format",
@@ -58,9 +61,16 @@ def experiments(
             f"No {CONFIG_FILE} here. Run labnotes init, or pass -c PATH."
         )
     match name, action:
+        case "new", _:
+            try:
+                path = create_experiment(config, action)
+            except ValueError as error:
+                raise click.ClickException(str(error)) from error
+            click.echo(f"Created {path / 'experiment.toml'}")
+            return
         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
@@ -70,6 +80,8 @@ def experiments(
             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)
+    if action not in (None, "runs"):
+        raise click.UsageError(f"Unknown action {action}. Use runs or run.")
     rows = asyncio.run(experiment_rows(config, name, action))
     if rows is None:
         raise click.ClickException(f"No experiment named {name}.")

{labnotes-0.0.16 → labnotes-0.0.18}/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.16 → labnotes-0.0.18}/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.16 → labnotes-0.0.18}/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.16 → labnotes-0.0.18}/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.16 → labnotes-0.0.18}/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 (