labnotes 0.0.11__tar.gz → 0.0.13__tar.gz

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

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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: labnotes
-Version: 0.0.11
+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,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 server
 ```
 
-- `--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,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. 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
-```
+`--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`.
 
 ## Agent skill
 

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

@@ -3,12 +3,23 @@
 Browse experiment designs, notes, and run data from a folder.
 
 ```sh
-uvx labnotes --experiments-folder experiments --data-folder data
+uvx labnotes server
 ```
 
-- `--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.
 
@@ -24,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. 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
-```
+`--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`.
 
 ## 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/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.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.11 → labnotes-0.0.13}/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.13/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.11/src/labnotes/cli.py → labnotes-0.0.13/src/labnotes/server.py

@@ -1,28 +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.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.command(help="Serve the experiments and their run data as a local site.")
 @click.option(
     "--experiments-folder",
     type=click.Path(path_type=Path),
@@ -43,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",
@@ -58,34 +42,21 @@ 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,
     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
+    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
     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))
-        return
+        raise click.UsageError(
+            f"--experiments-folder and --data-folder are required without a {CONFIG_FILE}."
+        )
     # 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())
@@ -98,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.11/src/labnotes/context.md

@@ -1,27 +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. 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

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