labnotes 0.0.17__tar.gz → 0.0.19__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: labnotes
-Version: 0.0.17
+Version: 0.0.19
 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,6 +69,10 @@ 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:
 
@@ -94,6 +98,9 @@ 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.
+To exclude a run, add `"excluded": true` and an optional `"reason"` to its
+`run.json`. An excluded run doesn't count toward `repeats`, so the next `run`
+replaces it; both show as columns in `runs`.
 
 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

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

@@ -46,6 +46,10 @@ 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:
 
@@ -71,6 +75,9 @@ 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.
+To exclude a run, add `"excluded": true` and an optional `"reason"` to its
+`run.json`. An excluded run doesn't count toward `repeats`, so the next `run`
+replaces it; both show as columns in `runs`.
 
 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

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

@@ -36,6 +36,10 @@ 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:
 
@@ -61,6 +65,9 @@ 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.
+To exclude a run, add `"excluded": true` and an optional `"reason"` to its
+`run.json`. An excluded run doesn't count toward `repeats`, so the next `run`
+replaces it; both show as columns in `runs`.
 
 A script run by labnotes should:
 

{labnotes-0.0.17 → labnotes-0.0.19}/src/labnotes/count_runs.py

@@ -1,10 +1,10 @@
 from dirsql import DirSQL
 
-from labnotes.sql_quote import quote_identifier, quote_string
+from labnotes.sql_quote import quote_identifier
 
 
 async def count_runs(
-    runs: DirSQL, study: str, completed_run: str, group_by: list[str] | None = None
+    runs: DirSQL, source: str, completed_run: str, group_by: list[str] | None = None
 ) -> list[dict[str, object]]:
     keys = [quote_identifier(key) for key in group_by or []]
     columns = "".join(f"{key}, " for key in keys)
@@ -12,5 +12,5 @@ async def count_runs(
     return await runs.query(
         f"SELECT {columns}COUNT(*) AS runs,"
         f" COALESCE(SUM(CASE WHEN ({completed_run}) THEN 1 ELSE 0 END), 0) AS completed"
-        f" FROM runs WHERE study = {quote_string(study)}{group}"
+        f" FROM {source}{group}"
     )

labnotes-0.0.19/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.17 → labnotes-0.0.19}/src/labnotes/experiments.py

@@ -4,6 +4,7 @@ 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
@@ -13,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",
@@ -57,6 +61,13 @@ 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 = run_tui if live else lambda start, title: run_headless(start)
@@ -69,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.17 → labnotes-0.0.19}/src/labnotes/list_runs.py

@@ -5,9 +5,9 @@ from labnotes.sql_quote import quote_identifier, quote_string
 
 
 async def list_runs(
-    runs: DirSQL, study: str, completed_run: str, view: RunView
+    runs: DirSQL, source: str, completed_run: str, view: RunView
 ) -> list[dict[str, object]]:
-    where = [f"study = {quote_string(study)}"]
+    where = []
     if view.status:
         negate = {"complete": "", "incomplete": "NOT "}[view.status]
         where.append(f"{negate}({completed_run})")
@@ -16,6 +16,7 @@ async def list_runs(
         f" lower({quote_string(value)})) > 0"
         for column, value in view.filters.items()
     ]
+    filtered = f" WHERE {' AND '.join(where)}" if where else ""
     direction = "DESC" if view.descending else "ASC"
     if view.sort == "status":
         order = f"labnotes_completed {direction}"
@@ -24,6 +25,6 @@ async def list_runs(
     else:
         order = "2 DESC"
     return await runs.query(
-        f"SELECT ({completed_run}) AS labnotes_completed, * FROM runs"
-        f" WHERE {' AND '.join(where)} ORDER BY {order}"
+        f"SELECT ({completed_run}) AS labnotes_completed, * FROM {source}"
+        f"{filtered} ORDER BY {order}"
     )

{labnotes-0.0.17 → labnotes-0.0.19}/src/labnotes/load_experiment.py

@@ -12,6 +12,7 @@ from labnotes.run_columns import run_columns
 from labnotes.sort_href import sort_href
 from labnotes.sql_quote import quote_string
 from labnotes.study_progress import study_progress
+from labnotes.study_runs import study_runs
 from labnotes.summarize_design import summarize_design
 
 
@@ -46,7 +47,9 @@ async def load_experiment(
     listed = (
         []
         if study is None
-        else await list_runs(runs, study, str(summary["completed_run"]), view)
+        else await list_runs(
+            runs, study_runs(study), str(summary["completed_run"]), view
+        )
     )
     return {
         "name": row["name"],

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

@@ -23,7 +23,11 @@ async def run_experiment(
     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]
+    finished = [
+        json.loads(str(run["params"]))
+        for run in runs
+        if run["exit_code"] == 0 and not run["excluded"]
+    ]
     plan = plan_runs(param_grid(experiment.params), experiment.repeats, finished)
     report({"event": "planned", "runs": len(plan), "concurrency": concurrency})
     running: set[asyncio.subprocess.Process] = set()

{labnotes-0.0.17 → labnotes-0.0.19}/src/labnotes/study_progress.py

@@ -4,6 +4,7 @@ from dirsql import DirSQL
 
 from labnotes.cell_progress import cell_progress
 from labnotes.count_runs import count_runs
+from labnotes.study_runs import study_runs
 
 
 async def study_progress(
@@ -22,11 +23,12 @@ async def study_progress(
     }
     if study is None:
         return progress
-    [totals] = await count_runs(runs, study, completed_run)
+    source = study_runs(study)
+    [totals] = await count_runs(runs, source, completed_run)
     progress.update(totals)
     if missing:
         return progress
-    grouped = await count_runs(runs, study, completed_run, group_by=list(varies))
+    grouped = await count_runs(runs, source, completed_run, group_by=list(varies))
     cells = cell_progress(varies, grouped)
     progress["cells"] = cells
     if isinstance(runs_per_cell, int):

labnotes-0.0.19/src/labnotes/study_runs.py

@@ -0,0 +1,5 @@
+from labnotes.sql_quote import quote_string
+
+
+def study_runs(study: str) -> str:
+    return f"(SELECT * FROM runs WHERE study = {quote_string(study)})"

{labnotes-0.0.17 → labnotes-0.0.19}/src/labnotes/tables/list_experiment_runs.py

@@ -5,6 +5,7 @@ from labnotes.sql_quote import quote_string
 
 async def list_experiment_runs(tables: DirSQL, name: str) -> list[dict[str, object]]:
     return await tables.query(
-        "SELECT id, created, ended, exit_code, error, params, folder FROM runs"
+        "SELECT id, created, ended, exit_code, error, excluded, reason, params, folder"
+        " FROM runs"
         f" WHERE experiment = {quote_string(name)} ORDER BY created, id"
     )

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

@@ -31,7 +31,8 @@ CREATE TABLE files (
 RUNS = """
 CREATE TABLE runs (
   experiment TEXT, id TEXT, folder TEXT, created TEXT, ended TEXT,
-  exit_code INTEGER, error TEXT, stdout TEXT, stderr TEXT, params TEXT,
+  exit_code INTEGER, error TEXT, excluded INTEGER, reason TEXT,
+  stdout TEXT, stderr TEXT, params TEXT,
   PRIMARY KEY (experiment, id)
 )
 """

{labnotes-0.0.17 → labnotes-0.0.19}/src/labnotes/tables/read_run.py

@@ -20,6 +20,8 @@ def read_run(root: Path, template: str, path: str) -> list[dict[str, object]]:
             "ended": run.get("ended"),
             "exit_code": run.get("exit_code"),
             "error": run.get("error"),
+            "excluded": run.get("excluded") is True,
+            "reason": run.get("reason"),
             "stdout": f"{folder}/stdout.log",
             "stderr": f"{folder}/stderr.log",
             "params": json.dumps(run.get("params", {})),