labnotes 0.0.10__tar.gz → 0.0.11__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: labnotes
-Version: 0.0.10
+Version: 0.0.11
 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>
@@ -46,3 +46,22 @@ 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.
+
+## 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" \
+  --experiments-folder experiments --data-folder data
+```
+
+## 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.11}/README.md

@@ -27,3 +27,22 @@ 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.
+
+## 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" \
+  --experiments-folder experiments --data-folder data
+```
+
+## 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.11}/src/labnotes/cli.py

@@ -6,26 +6,32 @@ 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.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(
     "--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 +60,28 @@ 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,
+    experiments_folder: Path | None,
+    data_folder: Path | None,
     kernel_idle_minutes: int,
     as_json: bool,
     **server_options: object,
 ) -> None:
+    if experiment == "context" and sql is None:
+        click.echo(context_guide(), nl=False)
+        return
+    if experiments_folder is None or data_folder is None:
+        raise click.UsageError("--experiments-folder and --data-folder are required.")
+    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.11/src/labnotes/context.md

@@ -0,0 +1,27 @@
+## 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. Pass both on every call, or set `LABNOTES_EXPERIMENTS_FOLDER` and `LABNOTES_DATA_FOLDER`:
+
+```sh
+uvx labnotes --experiments-folder experiments --data-folder data --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 --experiments-folder experiments --data-folder data
+```
+
+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" --experiments-folder experiments --data-folder data
+```
+
+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.11/src/labnotes/context_guide.py

@@ -0,0 +1,7 @@
+from importlib.metadata import version
+from importlib.resources import files
+
+
+def context_guide() -> str:
+    guide = files("labnotes").joinpath("context.md").read_text(encoding="utf-8")
+    return f"labnotes {version('labnotes')}\n\n{guide}"

labnotes-0.0.11/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.11/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() :]}"