labnotes 0.0.12__tar.gz → 0.0.13__tar.gz

{labnotes-0.0.12 → labnotes-0.0.13}/.gitignore

@@ -21,3 +21,5 @@ build/
 docs/.vitepress/cache
 docs/.vitepress/dist
 docs/node_modules/
+
+notes

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: labnotes
-Version: 0.0.12
+Version: 0.0.13
 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,7 +22,7 @@ Description-Content-Type: text/markdown
 Browse experiment designs, notes, and run data from a folder.
 
 ```sh
-uvx labnotes
+uvx labnotes server
 ```
 
 labnotes reads two folders, named in a `.labnotes.toml` at the project root:
@@ -54,19 +54,9 @@ 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. `--experiments-folder`
+`--ssl-*` set, and the rest. `labnotes server --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"
-```
+`LABNOTES_DATA_FOLDER`, override `.labnotes.toml`.
 
 ## Agent skill
 

{labnotes-0.0.12 → labnotes-0.0.13}/README.md

@@ -3,7 +3,7 @@
 Browse experiment designs, notes, and run data from a folder.
 
 ```sh
-uvx labnotes
+uvx labnotes server
 ```
 
 labnotes reads two folders, named in a `.labnotes.toml` at the project root:
@@ -35,19 +35,9 @@ 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. `--experiments-folder`
+`--ssl-*` set, and the rest. `labnotes server --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"
-```
+`LABNOTES_DATA_FOLDER`, override `.labnotes.toml`.
 
 ## Agent skill
 

labnotes-0.0.13/src/labnotes/cli.py

@@ -0,0 +1,38 @@
+from pathlib import Path
+
+import click
+
+from labnotes.context_guide import context_guide
+from labnotes.load_config import load_config
+from labnotes.read_config import CONFIG_FILE
+from labnotes.server import server
+
+
+@click.group(
+    invoke_without_command=True,
+    help="Manage experiments in a folder. `labnotes context` prints a guide for"
+    " coding agents.",
+)
+@click.version_option(package_name="labnotes")
+@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.pass_context
+def main(ctx: click.Context, config_path: Path | None) -> None:
+    if ctx.invoked_subcommand is None:
+        click.echo(ctx.get_help())
+        ctx.exit()
+    ctx.obj = config_path or Path.cwd() / CONFIG_FILE
+
+
+@main.command(help="Print a guide for coding agents.")
+@click.pass_context
+def context(ctx: click.Context) -> None:
+    click.echo(context_guide(load_config(ctx), Path.cwd()), nl=False)
+
+
+main.add_command(server)

labnotes-0.0.13/src/labnotes/context.md

@@ -0,0 +1,18 @@
+## 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.
+
+The run data lives in the data folder. Query it with [dirsql](https://dirsql.dev) and the data folder's `.dirsql.toml`, which declares the `runs` table:
+
+```sh
+uvx dirsql -c data/.dirsql.toml "SELECT * FROM runs LIMIT 1" --format json
+```
+
+`uvx labnotes server` serves the experiments and their runs as a local site.

labnotes-0.0.13/src/labnotes/load_config.py

@@ -0,0 +1,14 @@
+from pathlib import Path
+
+import click
+
+from labnotes.models import LabnotesConfig
+from labnotes.read_config import read_config
+
+
+def load_config(ctx: click.Context) -> LabnotesConfig | None:
+    path: Path = ctx.find_root().obj
+    try:
+        return read_config(path) if path.is_file() else None
+    except ValueError as error:
+        raise click.ClickException(str(error)) from error

labnotes-0.0.12/src/labnotes/cli.py → labnotes-0.0.13/src/labnotes/server.py

@@ -1,36 +1,18 @@
-import asyncio
-import json
 import os
 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.load_config import load_config
+from labnotes.read_config import CONFIG_FILE
 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. 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.command(help="Serve the experiments and their run data as a local site.")
 @click.option(
     "--experiments-folder",
     type=click.Path(path_type=Path),
@@ -51,12 +33,6 @@ OWN_OPTIONS = {"app", "factory", "app_dir", "version", "host", "port"}
     envvar=KERNEL_IDLE_MINUTES,
     help="Stop a note's Python kernel after this long without a run.",
 )
-@click.option(
-    "--json",
-    "as_json",
-    is_flag=True,
-    help="Print experiments as JSON instead of serving.",
-)
 @click.option(
     "-h",
     "--host",
@@ -66,26 +42,14 @@ OWN_OPTIONS = {"app", "factory", "app_dir", "version", "host", "port"}
 )
 @click.option("-p", "--port", type=int, default=8000, show_default=True)
 @click.pass_context
-def main(
+def server(
     ctx: click.Context,
-    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
+    config = load_config(ctx)
     if config is not None:
         experiments_folder = experiments_folder or config.experiments_folder
         data_folder = data_folder or config.data_folder
@@ -93,19 +57,6 @@ def main(
         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))
-        return
     # Through the environment so --reload and --workers child processes see them.
     os.environ[EXPERIMENTS_FOLDER] = str(experiments_folder.resolve())
     os.environ[DATA_FOLDER] = str(data_folder.resolve())
@@ -118,4 +69,4 @@ def main(
     )
 
 
-main.params += [p for p in uvicorn_main.params if p.name not in OWN_OPTIONS]
+server.params += [p for p in uvicorn_main.params if p.name not in OWN_OPTIONS]

labnotes-0.0.12/src/labnotes/context.md

@@ -1,34 +0,0 @@
-## 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/dump_experiments.py

@@ -1,15 +0,0 @@
-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
-
-
-async def dump_experiments(
-    experiments_folder: Path, data_folder: Path
-) -> list[dict[str, object]]:
-    experiments = open_experiments(experiments_folder)
-    runs = open_runs(data_folder)
-    await experiments.ready()
-    await runs.ready()
-    return await list_experiments(experiments, runs)

labnotes-0.0.12/src/labnotes/query_experiment.py

@@ -1,24 +0,0 @@
-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/scope_runs.py

@@ -1,14 +0,0 @@
-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() :]}"