labnotes 0.0.9__tar.gz → 0.0.11__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: labnotes
-Version: 0.0.9
+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.9 → 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.9 → labnotes-0.0.11}/src/labnotes/cli.py

@@ -6,29 +6,43 @@ 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.serve_app import DATA_FOLDER, EXPERIMENTS_FOLDER
+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.",
 )
+@click.option(
+    "--kernel-idle-minutes",
+    type=click.IntRange(min=1),
+    default=30,
+    show_default=True,
+    envvar=KERNEL_IDLE_MINUTES,
+    help="Stop a note's Python kernel after this long without a run.",
+)
 @click.option(
     "--json",
     "as_json",
@@ -46,11 +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))
@@ -58,6 +89,7 @@ def main(
     # 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())
+    os.environ[KERNEL_IDLE_MINUTES] = str(kernel_idle_minutes)
     ctx.invoke(
         uvicorn_main,
         app="labnotes.serve_app:serve_app",

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.9 → labnotes-0.0.11}/src/labnotes/create_app.py

@@ -24,6 +24,7 @@ from labnotes.pivot_cells import pivot_cells
 from labnotes.python_blocks import python_blocks
 from labnotes.saved_outputs import saved_outputs
 from labnotes.sql_quote import quote_string
+from labnotes.stop_idle_kernels import stop_idle_kernels
 
 HERE = Path(__file__).parent
 templates = Jinja2Templates(directory=HERE / "templates")
@@ -31,7 +32,9 @@ templates.env.filters["value"] = format_value
 templates.env.globals["asset"] = asset_url
 
 
-def create_app(experiments_folder: Path, data_folder: Path) -> Starlette:
+def create_app(
+    experiments_folder: Path, data_folder: Path, kernel_idle_minutes: float
+) -> Starlette:
     kernels: dict[tuple[str, str], NotebookKernel] = {}
 
     @asynccontextmanager
@@ -43,6 +46,7 @@ def create_app(experiments_folder: Path, data_folder: Path) -> Starlette:
         watchers = [
             asyncio.create_task(drain_watch(app.state.experiments)),
             asyncio.create_task(drain_watch(app.state.runs)),
+            asyncio.create_task(stop_idle_kernels(kernels, kernel_idle_minutes)),
         ]
         yield
         for watcher in watchers:
@@ -79,7 +83,7 @@ def create_app(experiments_folder: Path, data_folder: Path) -> Starlette:
             {"experiment": loaded, "pivot": pivot_cells(varies, cells)},
         )
 
-    async def run_block(request: Request) -> Response:
+    async def note_content(request: Request) -> str:
         if request.headers.get("content-type") != "application/json":
             raise HTTPException(415, "Send JSON")
         name = request.path_params["name"]
@@ -91,19 +95,35 @@ def create_app(experiments_folder: Path, data_folder: Path) -> Starlette:
         if not found:
             raise HTTPException(404, "No such note")
         [row] = found
-        blocks = python_blocks(str(row["content"]))
+        return str(row["content"])
+
+    async def run_block(request: Request) -> Response:
+        blocks = python_blocks(await note_content(request))
+        key = (request.path_params["name"], request.path_params["note"])
         block = (await request.json()).get("block")
         if not isinstance(block, int) or not 0 <= block < len(blocks):
             raise HTTPException(400, "No such block")
-        if (name, note) not in kernels:
-            kernels[(name, note)] = NotebookKernel(data_folder)
-        return HTMLResponse(await kernels[(name, note)].run(blocks[block]))
+        if key not in kernels:
+            kernels[key] = NotebookKernel(data_folder)
+        return HTMLResponse(await kernels[key].run(blocks[block]))
+
+    async def restart_kernel(request: Request) -> Response:
+        await note_content(request)
+        kernel = kernels.get((request.path_params["name"], request.path_params["note"]))
+        if kernel is not None:
+            await kernel.restart()
+        return Response(status_code=204)
 
     return Starlette(
         routes=[
             Route("/", index),
             Route("/experiments/{name}", experiment),
             Route("/experiments/{name}/notes/{note}/run", run_block, methods=["POST"]),
+            Route(
+                "/experiments/{name}/notes/{note}/restart",
+                restart_kernel,
+                methods=["POST"],
+            ),
             Mount("/static", StaticFiles(directory=HERE / "static"), name="static"),
         ],
         lifespan=lifespan,

{labnotes-0.0.9 → labnotes-0.0.11}/src/labnotes/load_experiment.py

@@ -6,6 +6,7 @@ from dirsql import DirSQL
 
 from labnotes.list_runs import list_runs
 from labnotes.parse_run_view import parse_run_view
+from labnotes.python_blocks import python_blocks
 from labnotes.render_markdown import render_markdown
 from labnotes.run_columns import run_columns
 from labnotes.sort_href import sort_href
@@ -59,6 +60,7 @@ async def load_experiment(
                     str(note["content"]),
                     outputs_for(str(note["name"]), str(note["content"])),
                 ),
+                "runnable": bool(python_blocks(str(note["content"]))),
             }
             for note in notes
         ],

labnotes-0.0.11/src/labnotes/notebook_kernel.py

@@ -0,0 +1,74 @@
+import asyncio
+import hashlib
+from pathlib import Path
+from time import monotonic
+
+from jupyter_client.asynchronous.client import AsyncKernelClient
+from jupyter_client.manager import AsyncKernelManager
+
+from labnotes.output_html import output_html
+
+QUIET = {"status", "execute_input"}
+
+
+def block_key(code: str) -> str:
+    return hashlib.sha256(code.encode()).hexdigest()
+
+
+class NotebookKernel:
+    """One live Python kernel per notes file; blocks run only when asked."""
+
+    def __init__(self, cwd: Path) -> None:
+        self.cwd = cwd
+        self.outputs: dict[str, str] = {}
+        self._lock = asyncio.Lock()
+        self._manager: AsyncKernelManager | None = None
+        self._client: AsyncKernelClient | None = None
+        self.last_used = monotonic()
+
+    async def _start(self) -> None:
+        self._manager = AsyncKernelManager(kernel_name="python3")
+        await self._manager.start_kernel(cwd=str(self.cwd))
+        self._client = self._manager.client()
+        self._client.start_channels()
+        await self._client.wait_for_ready(timeout=60)
+
+    async def run(self, code: str) -> str:
+        async with self._lock:
+            try:
+                if self._client is None:
+                    await self._start()
+                assert self._client is not None
+                messages: list[dict[str, object]] = []
+                await self._client.execute_interactive(
+                    code,
+                    output_hook=lambda message: messages.append(message),
+                    allow_stdin=False,
+                )
+                html = output_html(
+                    [
+                        {"msg_type": message["msg_type"], "content": message["content"]}
+                        for message in messages
+                        if message["msg_type"] not in QUIET
+                    ]
+                )
+                self.outputs[block_key(code)] = html
+                return html
+            finally:
+                self.last_used = monotonic()
+
+    async def stop(self) -> None:
+        client, manager = self._client, self._manager
+        self._client = self._manager = None
+        if client is not None:
+            client.stop_channels()
+        if manager is not None:
+            await manager.shutdown_kernel(now=True)
+
+    async def restart(self) -> None:
+        async with self._lock:
+            await self.stop()
+
+    async def stop_if_idle(self, idle_seconds: float) -> None:
+        if not self._lock.locked() and monotonic() - self.last_used > idle_seconds:
+            await self.stop()

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() :]}"

{labnotes-0.0.9 → labnotes-0.0.11}/src/labnotes/serve_app.py

@@ -7,9 +7,12 @@ from labnotes.create_app import create_app
 
 EXPERIMENTS_FOLDER = "LABNOTES_EXPERIMENTS_FOLDER"
 DATA_FOLDER = "LABNOTES_DATA_FOLDER"
+KERNEL_IDLE_MINUTES = "LABNOTES_KERNEL_IDLE_MINUTES"
 
 
 def serve_app() -> Starlette:
     return create_app(
-        Path(os.environ[EXPERIMENTS_FOLDER]), Path(os.environ[DATA_FOLDER])
+        Path(os.environ[EXPERIMENTS_FOLDER]),
+        Path(os.environ[DATA_FOLDER]),
+        int(os.environ[KERNEL_IDLE_MINUTES]),
     )

{labnotes-0.0.9 → labnotes-0.0.11}/src/labnotes/static/labnotes.css

@@ -414,6 +414,8 @@ h2 .clear { font-family: var(--sans); font-size: 0.82rem; margin-left: 0.8rem; c
   position: absolute;
   top: 0.5rem;
   right: 0.5rem;
+}
+.cell .run, .note-name .restart {
   font: inherit;
   font-family: var(--sans);
   font-size: 0.75rem;
@@ -424,8 +426,9 @@ h2 .clear { font-family: var(--sans); font-size: 0.82rem; margin-left: 0.8rem; c
   color: var(--ink-2);
   cursor: pointer;
 }
-.cell .run:hover { color: var(--accent); border-color: var(--accent); }
-.cell .run:disabled { cursor: progress; opacity: 0.6; }
+.cell .run:hover, .note-name .restart:hover { color: var(--accent); border-color: var(--accent); }
+.cell .run:disabled, .note-name .restart:disabled { cursor: progress; opacity: 0.6; }
+.note-name:has(.restart) { display: flex; align-items: center; justify-content: space-between; padding-top: 0.45rem; padding-bottom: 0.45rem; }
 .cell-output { display: block; }
 .cell-output:not(:empty) { margin-top: 0.4rem; padding-left: 0.9rem; border-left: 2px solid var(--accent-soft); overflow-x: auto; }
 .cell-output pre { background: none; border: 0; padding: 0.3rem 0; }

{labnotes-0.0.9 → labnotes-0.0.11}/src/labnotes/static/run-cell.js

@@ -21,3 +21,24 @@ for (const note of document.querySelectorAll(".note[data-run-url]")) {
     });
   }
 }
+
+for (const note of document.querySelectorAll(".note[data-restart-url]")) {
+  const button = note.querySelector(".restart");
+  if (!button) continue;
+  button.addEventListener("click", async () => {
+    button.disabled = true;
+    button.textContent = "Restarting";
+    try {
+      const response = await fetch(note.dataset.restartUrl, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: "{}",
+      });
+      button.textContent = response.ok ? "Restarted" : `${response.status} ${response.statusText}`;
+      await new Promise((resolve) => setTimeout(resolve, 1500));
+    } finally {
+      button.disabled = false;
+      button.textContent = "Restart";
+    }
+  });
+}

labnotes-0.0.11/src/labnotes/stop_idle_kernels.py

@@ -0,0 +1,13 @@
+import asyncio
+from collections.abc import Mapping
+
+from labnotes.notebook_kernel import NotebookKernel
+
+
+async def stop_idle_kernels(
+    kernels: Mapping[tuple[str, str], NotebookKernel], idle_minutes: float
+) -> None:
+    while True:
+        await asyncio.sleep(60)
+        for kernel in list(kernels.values()):
+            await kernel.stop_if_idle(idle_minutes * 60)

{labnotes-0.0.9 → labnotes-0.0.11}/src/labnotes/templates/experiment.html

@@ -111,8 +111,8 @@
 <section id="notes" class="block">
   <h2>Notes</h2>
   {% for note in e.notes %}
-  <article class="note" data-run-url="{{ url_for('run_block', name=e.name, note=note.name) }}">
-    <header class="note-name">{{ note.name }}</header>
+  <article class="note" data-run-url="{{ url_for('run_block', name=e.name, note=note.name) }}" data-restart-url="{{ url_for('restart_kernel', name=e.name, note=note.name) }}">
+    <header class="note-name">{{ note.name }}{% if note.runnable %}<button type="button" class="restart" title="Stop this note's Python kernel. The next Run starts a fresh one.">Restart</button>{% endif %}</header>
     <div class="prose">{{ note.html | safe }}</div>
   </article>
   {% endfor %}

labnotes-0.0.9/src/labnotes/notebook_kernel.py

@@ -1,59 +0,0 @@
-import asyncio
-import hashlib
-from pathlib import Path
-
-from jupyter_client.asynchronous.client import AsyncKernelClient
-from jupyter_client.manager import AsyncKernelManager
-
-from labnotes.output_html import output_html
-
-QUIET = {"status", "execute_input"}
-
-
-def block_key(code: str) -> str:
-    return hashlib.sha256(code.encode()).hexdigest()
-
-
-class NotebookKernel:
-    """One live Python kernel per notes file; blocks run only when asked."""
-
-    def __init__(self, cwd: Path) -> None:
-        self.cwd = cwd
-        self.outputs: dict[str, str] = {}
-        self._lock = asyncio.Lock()
-        self._manager: AsyncKernelManager | None = None
-        self._client: AsyncKernelClient | None = None
-
-    async def _start(self) -> None:
-        self._manager = AsyncKernelManager(kernel_name="python3")
-        await self._manager.start_kernel(cwd=str(self.cwd))
-        self._client = self._manager.client()
-        self._client.start_channels()
-        await self._client.wait_for_ready(timeout=60)
-
-    async def run(self, code: str) -> str:
-        async with self._lock:
-            if self._client is None:
-                await self._start()
-            assert self._client is not None
-            messages: list[dict[str, object]] = []
-            await self._client.execute_interactive(
-                code,
-                output_hook=lambda message: messages.append(message),
-                allow_stdin=False,
-            )
-            html = output_html(
-                [
-                    {"msg_type": message["msg_type"], "content": message["content"]}
-                    for message in messages
-                    if message["msg_type"] not in QUIET
-                ]
-            )
-            self.outputs[block_key(code)] = html
-            return html
-
-    async def stop(self) -> None:
-        if self._client is not None:
-            self._client.stop_channels()
-        if self._manager is not None:
-            await self._manager.shutdown_kernel(now=True)