labnotes 0.0.11__tar.gz → 0.0.12__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: labnotes
-Version: 0.0.11
+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,8 +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`
+`--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
@@ -53,8 +65,7 @@ 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
+uvx labnotes models-effort "SELECT model, COUNT(*) AS n FROM runs GROUP BY 1"
 ```
 
 ## Agent skill

{labnotes-0.0.11 → labnotes-0.0.12}/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
 ```
 
-- `--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,8 +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`
+`--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
@@ -34,8 +46,7 @@ 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
+uvx labnotes models-effort "SELECT model, COUNT(*) AS n FROM runs GROUP BY 1"
 ```
 
 ## Agent skill

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

@@ -9,6 +9,7 @@ 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.
@@ -23,6 +24,13 @@ OWN_OPTIONS = {"app", "factory", "app_dir", "version", "host", "port"}
 @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),
@@ -62,17 +70,29 @@ def main(
     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(), nl=False)
+        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("--experiments-folder and --data-folder are required.")
+        raise click.UsageError(
+            f"--experiments-folder and --data-folder are required without a {CONFIG_FILE}."
+        )
     if experiment is not None:
         try:
             result = asyncio.run(

{labnotes-0.0.11 → labnotes-0.0.12}/src/labnotes/context.md

@@ -1,9 +1,16 @@
 ## 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`:
+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 --experiments-folder experiments --data-folder data --json
+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.
@@ -13,13 +20,13 @@ uvx labnotes --experiments-folder experiments --data-folder data --json
 Name an experiment to see what has run for it, as JSON:
 
 ```sh
-uvx labnotes models-effort --experiments-folder experiments --data-folder data
+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" --experiments-folder experiments --data-folder data
+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`.

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.11 → 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/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/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}"