Metadata-Version: 2.5
Name: labnotes
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>
License-Expression: MIT
Requires-Python: >=3.12
Requires-Dist: click>=8.5.0
Requires-Dist: dirsql>=0.4.110
Requires-Dist: ipykernel>=7.4.0
Requires-Dist: jinja2>=3.1.6
Requires-Dist: jupyter-client>=8.10.0
Requires-Dist: markdown-it-py>=4.2.0
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: starlette>=1.8.0
Requires-Dist: uvicorn>=0.54.0
Description-Content-Type: text/markdown

# 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.
