labnotes 0.0.10__tar.gz → 0.0.12__tar.gz

{labnotes-0.0.10 → labnotes-0.0.12}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: labnotes
-Version: 0.0.10
+Version: 0.0.12
 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>
@@ -22,12 +22,23 @@ Description-Content-Type: text/markdown
 Browse experiment designs, notes, and run data from a folder.
 
 ```sh
-uvx labnotes --experiments-folder experiments --data-folder data
+uvx labnotes
 ```
 
-- `--experiments-folder` holds one subfolder per experiment, each with a
+labnotes reads two folders, named in a `.labnotes.toml` at the project root:
+
+```toml
+experiments = "experiments"
+data = "data"
+```
+
+Both keys are optional and default to the values above. Paths are relative to
+`.labnotes.toml`, or absolute, or start with `~`. labnotes reads the file from
+the working folder, or from the path given with `-c`.
+
+- `experiments` holds one subfolder per experiment, each with a
   `design.yaml` (with a `study` key) and any number of markdown notes.
-- `--data-folder` holds the run data and a `.dirsql.toml` that declares a
+- `data` holds the run data and a `.dirsql.toml` that declares a
   `runs` table with a `study` column. An experiment's runs are the rows whose
   `study` matches its design's.
 
@@ -43,6 +54,25 @@ of values), `runs_per_cell`, and `completed_run`, a SQL condition over the
 `-h`/`--host` and `-p`/`--port` change where it listens; `-h 0.0.0.0` (or a
 Tailscale IP) serves beyond localhost. Every other uvicorn option passes
 through: `--reload`, `--workers`, `--proxy-headers`, `--root-path`, the
-`--ssl-*` set, and the rest. `labnotes --help` lists them. The folders can also
-come from `LABNOTES_EXPERIMENTS_FOLDER` and `LABNOTES_DATA_FOLDER`. `--json`
+`--ssl-*` set, and the rest. `labnotes --help` lists them. `--experiments-folder`
+and `--data-folder`, or `LABNOTES_EXPERIMENTS_FOLDER` and
+`LABNOTES_DATA_FOLDER`, override `.labnotes.toml`. `--json`
 prints the experiments as JSON and exits.
+
+## From the command line
+
+Name an experiment to print what has run for it as JSON. Add SQL to query
+that experiment's runs: `runs` holds only its runs, `main.runs` every run.
+
+```sh
+uvx labnotes models-effort "SELECT model, COUNT(*) AS n FROM runs GROUP BY 1"
+```
+
+## Agent skill
+
+```sh
+npx skills add thekevinscott/labnotes
+```
+
+The skill tells a coding agent to run `labnotes context`, which prints a usage
+guide for the installed version.

labnotes-0.0.12/README.md

@@ -0,0 +1,59 @@
+# labnotes
+
+Browse experiment designs, notes, and run data from a folder.
+
+```sh
+uvx labnotes
+```
+
+labnotes reads two folders, named in a `.labnotes.toml` at the project root:
+
+```toml
+experiments = "experiments"
+data = "data"
+```
+
+Both keys are optional and default to the values above. Paths are relative to
+`.labnotes.toml`, or absolute, or start with `~`. labnotes reads the file from
+the working folder, or from the path given with `-c`.
+
+- `experiments` holds one subfolder per experiment, each with a
+  `design.yaml` (with a `study` key) and any number of markdown notes.
+- `data` holds the run data and a `.dirsql.toml` that declares a
+  `runs` table with a `study` column. An experiment's runs are the rows whose
+  `study` matches its design's.
+
+That serves a local site at http://127.0.0.1:8000: a table of experiments,
+and a page per experiment with its parameters, its notes, progress per cell of
+the design grid, and every run so far. Both folders are watched, so a reload
+shows new runs and edited notes.
+
+`design.yaml` keys the site reads: `study`, `fixed`, `varies` (each key a list
+of values), `runs_per_cell`, and `completed_run`, a SQL condition over the
+`runs` table that marks a run as complete. Anything else shows up as-is.
+
+`-h`/`--host` and `-p`/`--port` change where it listens; `-h 0.0.0.0` (or a
+Tailscale IP) serves beyond localhost. Every other uvicorn option passes
+through: `--reload`, `--workers`, `--proxy-headers`, `--root-path`, the
+`--ssl-*` set, and the rest. `labnotes --help` lists them. `--experiments-folder`
+and `--data-folder`, or `LABNOTES_EXPERIMENTS_FOLDER` and
+`LABNOTES_DATA_FOLDER`, override `.labnotes.toml`. `--json`
+prints the experiments as JSON and exits.
+
+## From the command line
+
+Name an experiment to print what has run for it as JSON. Add SQL to query
+that experiment's runs: `runs` holds only its runs, `main.runs` every run.
+
+```sh
+uvx labnotes models-effort "SELECT model, COUNT(*) AS n FROM runs GROUP BY 1"
+```
+
+## Agent skill
+
+```sh
+npx skills add thekevinscott/labnotes
+```
+
+The skill tells a coding agent to run `labnotes context`, which prints a usage
+guide for the installed version.

{labnotes-0.0.10 → labnotes-0.0.12}/src/labnotes/cli.py

@@ -6,26 +6,40 @@ from pathlib import Path
 import click
 from uvicorn.main import main as uvicorn_main
 
+from labnotes.context_guide import context_guide
 from labnotes.dump_experiments import dump_experiments
+from labnotes.query_experiment import query_experiment
+from labnotes.read_config import CONFIG_FILE, read_config
 from labnotes.serve_app import DATA_FOLDER, EXPERIMENTS_FOLDER, KERNEL_IDLE_MINUTES
 
 # labnotes owns these; the rest of uvicorn's options pass straight through.
 OWN_OPTIONS = {"app", "factory", "app_dir", "version", "host", "port"}
 
 
-@click.command(help="Browse experiments and their run data.")
+@click.command(
+    help="Browse experiments and their run data. With EXPERIMENT, print what has"
+    " run as JSON; with SQL too, query that experiment's runs. `labnotes context`"
+    " prints a guide for coding agents."
+)
 @click.version_option(package_name="labnotes")
+@click.argument("experiment", required=False)
+@click.argument("sql", required=False)
+@click.option(
+    "-c",
+    "--config",
+    "config_path",
+    type=click.Path(path_type=Path, dir_okay=False, exists=True),
+    help=f"Project config. Default: {CONFIG_FILE} in the working folder, if there.",
+)
 @click.option(
     "--experiments-folder",
     type=click.Path(path_type=Path),
-    required=True,
     envvar=EXPERIMENTS_FOLDER,
     help="One subfolder per experiment, each with a design.yaml and markdown notes.",
 )
 @click.option(
     "--data-folder",
     type=click.Path(path_type=Path),
-    required=True,
     envvar=DATA_FOLDER,
     help="Run data, with a .dirsql.toml declaring a runs table that has a study column.",
 )
@@ -54,12 +68,40 @@ OWN_OPTIONS = {"app", "factory", "app_dir", "version", "host", "port"}
 @click.pass_context
 def main(
     ctx: click.Context,
-    experiments_folder: Path,
-    data_folder: Path,
+    experiment: str | None,
+    sql: str | None,
+    config_path: Path | None,
+    experiments_folder: Path | None,
+    data_folder: Path | None,
     kernel_idle_minutes: int,
     as_json: bool,
     **server_options: object,
 ) -> None:
+    cwd = Path.cwd()
+    config_path = config_path or cwd / CONFIG_FILE
+    try:
+        config = read_config(config_path) if config_path.is_file() else None
+    except ValueError as error:
+        raise click.ClickException(str(error)) from error
+    if experiment == "context" and sql is None:
+        click.echo(context_guide(config, cwd), nl=False)
+        return
+    if config is not None:
+        experiments_folder = experiments_folder or config.experiments_folder
+        data_folder = data_folder or config.data_folder
+    if experiments_folder is None or data_folder is None:
+        raise click.UsageError(
+            f"--experiments-folder and --data-folder are required without a {CONFIG_FILE}."
+        )
+    if experiment is not None:
+        try:
+            result = asyncio.run(
+                query_experiment(experiments_folder, data_folder, experiment, sql)
+            )
+        except (LookupError, RuntimeError) as error:
+            raise click.ClickException(str(error)) from error
+        click.echo(json.dumps(result, indent=2))
+        return
     if as_json:
         experiments = asyncio.run(dump_experiments(experiments_folder, data_folder))
         click.echo(json.dumps(experiments, indent=2))

labnotes-0.0.12/src/labnotes/context.md

@@ -0,0 +1,34 @@
+## Usage
+
+labnotes reads two folders. 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. A project that uses labnotes has a `.labnotes.toml` at its root; labnotes reads it from the working folder, so run labnotes from the project root, or pass `-c PATH`. The lines above this guide name the one found and the folders it resolves to, or say there is none. Its keys are optional:
+
+```toml
+experiments = "experiments"  # the default
+data = "data"                # relative to .labnotes.toml, absolute, or ~
+```
+
+`--experiments-folder` and `--data-folder`, or `LABNOTES_EXPERIMENTS_FOLDER` and `LABNOTES_DATA_FOLDER`, override either key. Without a `.labnotes.toml`, pass both.
+
+```sh
+uvx labnotes --json
+```
+
+`--json` lists every experiment: its name, study, the design's fixed and varied conditions, the target run count, and how many runs have run and completed, overall and per cell.
+
+### One experiment
+
+Name an experiment to see what has run for it, as JSON:
+
+```sh
+uvx labnotes models-effort
+```
+
+Add SQL to query its runs. `runs` holds only that experiment's runs, matched on the study in its `design.yaml`; `main.runs` holds every run in the data folder. The query goes through [dirsql](https://dirsql.dev), so it is SQLite and read-only:
+
+```sh
+uvx labnotes models-effort "SELECT model, effort, COUNT(*) AS n FROM runs GROUP BY 1, 2"
+```
+
+stdout is one JSON array of row objects. The columns are whatever the data folder's `.dirsql.toml` declares; `SELECT * FROM runs LIMIT 1` shows them. A run counts as completed when the design's `completed_run` SQL expression is true; the one-experiment JSON prints it, so reuse it in a `WHERE`.
+
+An unknown experiment, an experiment without a `study`, or bad SQL prints an error to stderr and exits `1`. An experiment named `context` cannot be queried this way.

labnotes-0.0.12/src/labnotes/context_guide.py

@@ -0,0 +1,22 @@
+from importlib.metadata import version
+from importlib.resources import files
+from pathlib import Path
+
+from labnotes.read_config import CONFIG_FILE
+from labnotes.models import LabnotesConfig
+
+
+def context_guide(config: LabnotesConfig | None, cwd: Path) -> str:
+    guide = files("labnotes").joinpath("context.md").read_text(encoding="utf-8")
+    if config is None:
+        project = (
+            f"No {CONFIG_FILE} in {cwd}. If this project uses labnotes, run it"
+            f" from the folder that holds {CONFIG_FILE}, or pass -c PATH."
+        )
+    else:
+        project = (
+            f"Config: {config.path}\n"
+            f"Experiments folder: {config.experiments_folder}\n"
+            f"Data folder: {config.data_folder}"
+        )
+    return f"labnotes {version('labnotes')}\n\n{project}\n\n{guide}"

{labnotes-0.0.10 → labnotes-0.0.12}/src/labnotes/models.py

@@ -1,4 +1,5 @@
 from dataclasses import dataclass, field
+from pathlib import Path
 
 
 @dataclass(frozen=True)
@@ -7,3 +8,10 @@ class RunView:
     descending: bool = False
     status: str | None = None
     filters: dict[str, str] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class LabnotesConfig:
+    path: Path
+    experiments_folder: Path
+    data_folder: Path

labnotes-0.0.12/src/labnotes/query_experiment.py

@@ -0,0 +1,24 @@
+from pathlib import Path
+
+from labnotes.list_experiments import list_experiments
+from labnotes.open_experiments import open_experiments
+from labnotes.open_runs import open_runs
+from labnotes.scope_runs import scope_runs
+
+
+async def query_experiment(
+    experiments_folder: Path, data_folder: Path, name: str, sql: str | None
+) -> object:
+    experiments = open_experiments(experiments_folder)
+    runs = open_runs(data_folder)
+    await experiments.ready()
+    await runs.ready()
+    listed = await list_experiments(experiments, runs)
+    experiment = next((row for row in listed if row["name"] == name), None)
+    if experiment is None:
+        raise LookupError(f"no experiment named {name!r}")
+    if sql is None:
+        return experiment
+    if experiment["study"] is None:
+        raise LookupError(f"{name!r} has no study in its design.yaml")
+    return await runs.query(scope_runs(sql, str(experiment["study"])))

labnotes-0.0.12/src/labnotes/read_config.py

@@ -0,0 +1,23 @@
+import tomllib
+from pathlib import Path
+
+from labnotes.models import LabnotesConfig
+
+CONFIG_FILE = ".labnotes.toml"
+DEFAULTS = {"experiments": "experiments", "data": "data"}
+
+
+def read_config(path: Path) -> LabnotesConfig:
+    with path.open("rb") as file:
+        values = tomllib.load(file)
+    unknown = sorted(values.keys() - DEFAULTS.keys())
+    if unknown:
+        raise ValueError(f"{path}: unknown keys {', '.join(unknown)}")
+    folder = path.resolve().parent
+    folders = {}
+    for key, default in DEFAULTS.items():
+        value = values.get(key, default)
+        if not isinstance(value, str):
+            raise ValueError(f"{path}: {key} must be a string")
+        folders[key] = folder / Path(value).expanduser()
+    return LabnotesConfig(path.resolve(), folders["experiments"], folders["data"])

labnotes-0.0.12/src/labnotes/scope_runs.py

@@ -0,0 +1,14 @@
+import re
+
+from labnotes.sql_quote import quote_string
+
+LEADING_WITH = re.compile(r"\s*WITH(\s+RECURSIVE)?\s+", re.IGNORECASE)
+
+
+def scope_runs(sql: str, study: str) -> str:
+    runs = f"runs AS (SELECT * FROM main.runs WHERE study = {quote_string(study)})"
+    leading_with = LEADING_WITH.match(sql)
+    if leading_with is None:
+        return f"WITH {runs} {sql}"
+    recursive = " RECURSIVE" if leading_with.group(1) else ""
+    return f"WITH{recursive} {runs}, {sql[leading_with.end() :]}"

labnotes-0.0.10/README.md

@@ -1,29 +0,0 @@
-# labnotes
-
-Browse experiment designs, notes, and run data from a folder.
-
-```sh
-uvx labnotes --experiments-folder experiments --data-folder data
-```
-
-- `--experiments-folder` holds one subfolder per experiment, each with a
-  `design.yaml` (with a `study` key) and any number of markdown notes.
-- `--data-folder` holds the run data and a `.dirsql.toml` that declares a
-  `runs` table with a `study` column. An experiment's runs are the rows whose
-  `study` matches its design's.
-
-That serves a local site at http://127.0.0.1:8000: a table of experiments,
-and a page per experiment with its parameters, its notes, progress per cell of
-the design grid, and every run so far. Both folders are watched, so a reload
-shows new runs and edited notes.
-
-`design.yaml` keys the site reads: `study`, `fixed`, `varies` (each key a list
-of values), `runs_per_cell`, and `completed_run`, a SQL condition over the
-`runs` table that marks a run as complete. Anything else shows up as-is.
-
-`-h`/`--host` and `-p`/`--port` change where it listens; `-h 0.0.0.0` (or a
-Tailscale IP) serves beyond localhost. Every other uvicorn option passes
-through: `--reload`, `--workers`, `--proxy-headers`, `--root-path`, the
-`--ssl-*` set, and the rest. `labnotes --help` lists them. The folders can also
-come from `LABNOTES_EXPERIMENTS_FOLDER` and `LABNOTES_DATA_FOLDER`. `--json`
-prints the experiments as JSON and exits.