nuboard 0.20.0__tar.gz

nuboard-0.20.0/.github/workflows/ci.yml

@@ -0,0 +1,71 @@
+name: Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+# A new push to a branch or PR cancels its run still going
+concurrency:
+  group: tests-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  python:
+    name: Python ${{ matrix.python }} on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python: ["3.10", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 10
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+          cache-dependency-path: frontend/pnpm-lock.yaml
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.python }}
+      - name: Build the frontend
+        working-directory: frontend
+        run: |
+          pnpm install --frozen-lockfile
+          pnpm build
+      - run: uv sync --locked
+      # A test that hangs fails after 2 minutes and is named in the log
+      - run: uv run pytest tests -q --timeout=120
+      - run: uv run ruff check src tests
+        if: matrix.os == 'ubuntu-latest'
+      - run: uv run pyright src
+        if: matrix.os == 'ubuntu-latest'
+
+  frontend:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    defaults:
+      run:
+        working-directory: frontend
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 10
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+          cache-dependency-path: frontend/pnpm-lock.yaml
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm check
+      - run: pnpm lint
+      - run: pnpm test

nuboard-0.20.0/.github/workflows/docs.yml

@@ -0,0 +1,41 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.12"
+      - run: uv sync --locked
+      - run: uv run mkdocs build --strict
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

nuboard-0.20.0/.github/workflows/release.yml

@@ -0,0 +1,52 @@
+name: Release
+
+# Publishing a GitHub release builds the wheel and sdist and uploads them to
+# PyPI through Trusted Publishing, so no PyPI token is stored in the repository.
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 10
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.12"
+      - run: uv sync --locked
+      - name: Check the release matches the version
+        run: |
+          uv run pytest tests/test_release.py -q
+          test "${GITHUB_REF_NAME#v}" = "$(uv run python -c 'import nuboard; print(nuboard.__version__)')"
+      - run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    environment:
+      name: pypi
+      url: https://pypi.org/p/nuboard
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

nuboard-0.20.0/.github/workflows/windows.yml

@@ -0,0 +1,35 @@
+name: Windows
+
+# Run by hand from the Actions tab while Windows support is being checked; it
+# never runs on pushes or pull requests, so it cannot mark them as failing.
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  python:
+    runs-on: windows-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 10
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+          cache-dependency-path: frontend/pnpm-lock.yaml
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.13"
+      - name: Build the frontend
+        working-directory: frontend
+        run: |
+          pnpm install --frozen-lockfile
+          pnpm build
+      - run: uv sync --locked
+      # A test that hangs fails after 2 minutes and is named in the log
+      - run: uv run pytest tests -v --timeout=120

nuboard-0.20.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.py[cod]
+.venv/
+.pytest_cache/
+.ruff_cache/
+dist/
+build/
+site/
+*.egg-info/
+# built frontend: produced by `pnpm build`, bundled into wheels by hatch_build.py
+src/nuboard/static/
+# local run data
+experiments/
+demo-runs/
+.DS_Store

nuboard-0.20.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Esteban Gómez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

nuboard-0.20.0/PKG-INFO

@@ -0,0 +1,144 @@
+Metadata-Version: 2.5
+Name: nuboard
+Version: 0.20.0
+Summary: A fast, local, folder-based experiment tracker and viewer for ML training.
+Project-URL: Homepage, https://eagomez2.github.io/nuboard/
+Project-URL: Documentation, https://eagomez2.github.io/nuboard/
+Project-URL: Source, https://github.com/eagomez2/nuboard
+Project-URL: Issues, https://github.com/eagomez2/nuboard/issues
+Project-URL: Changelog, https://eagomez2.github.io/nuboard/changelog/
+Author: Esteban Gómez
+License-Expression: MIT
+License-File: LICENSE
+Keywords: experiment-tracking,machine-learning,tensorboard,visualization
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.23
+Requires-Dist: pyarrow>=14
+Requires-Dist: starlette>=0.37
+Requires-Dist: uvicorn>=0.29
+Provides-Extra: viewer
+Description-Content-Type: text/markdown
+
+<p align="center"><img src="https://raw.githubusercontent.com/eagomez2/nuboard/main/docs/assets/logo.svg" width="72" alt=""></p>
+
+<h1 align="center">NuBoard</h1>
+
+<p align="center"><b>Experiment tracking that lives in a folder.</b><br>
+Log from Python with three calls. Every run is a folder. View thousands of runs in your browser.</p>
+
+![Charts page: a learning-rate sweep grouped by lr, mean ± std over three seeds](https://raw.githubusercontent.com/eagomez2/nuboard/main/docs/assets/charts-light.png)
+
+```python
+import nuboard as nb
+
+with nb.init("my-project", run_name="baseline", config={"lr": 3e-4}) as run:
+    for step in range(10_000):
+        loss = train_step()
+        run.add_scalar({"train/loss": loss}, step=step)  # ~3 µs, never blocks training
+```
+
+```bash
+nuboard up experiments        # http://localhost:6070
+```
+
+## Why
+
+- **No setup.** No account, no server, no database. `pip install nuboard` gives
+  you logging and the viewer; logging uses only the standard library, so it
+  adds nothing to the import time of a training script.
+- **Folder-contained.** Each run is one folder (`run.json`, an append-only
+  binary log, a media pack, a Parquet file at the end). Copy it, rsync it, zip
+  it, delete it.
+- **Fast.** Logging is a deque append; a background thread writes columnar
+  frames. The viewer reads a million points in about a tenth of a second and
+  lists thousands of runs instantly.
+- **Records what you forget.** Config, git commit and uncommitted diff,
+  installed packages, GPUs, command line, rank, console output and CPU, memory
+  and GPU use, automatically.
+- **Crash-safe.** A killed process loses at most the last second of data; torn
+  writes are ignored; crashes are marked with their traceback.
+
+## Quick start
+
+```bash
+pip install nuboard                   # or: uv pip install nuboard
+nuboard demo demo-runs --up --open    # 4 projects, 31 runs, one live run
+```
+
+Then try `where tags has "sweep" group by config.optim.lr` in the query bar and
+open the Charts page. The [quickstart](https://eagomez2.github.io/nuboard/quickstart/) has a tour, and
+[installation](https://eagomez2.github.io/nuboard/installation/) covers building from source.
+
+## What's in 0.13
+
+| Area | Included |
+| --- | --- |
+| Python API | `init` (+ resume, fork, ranks), `add_scalar`, `add_file`, `add_text`, `add_image`, `add_audio`, `add_video`, `add_figure`, `add_pr_curve`, `add_histogram`, `add_table`, `add_point_cloud`, `add_html`, `add_artifact` (copies or references), `use_artifact` (across projects), `nb.add_artifact`, `nb.get_artifact`, `finish`, context manager; system scalars (CPU, memory, GPU) and console capture |
+| Storage | documented [log format](https://eagomez2.github.io/nuboard/reference/format/), Parquet compaction with zoom levels, versioned artifacts, collections |
+| Analysis | `nb.load("project").scalars("loss", group_by="config.lr")` returns Arrow tables; properties, collections and alerts per run |
+| Runs | query language, stars, Markdown notes, archive, typed properties, tag editing, column chooser, collections, saved views, run details and config/file diffs |
+| Charts | grouped lines with bands, smoothing, zoom, linked crosshair, inspector, live updates, alerts strip, x axis by any scalar (tokens, epochs), solo or show all series |
+| Media | images, video, audio (waveform + spectrogram player with notes, or the browser's player), per-example tables compared across steps, PR curves, distributions over steps, point clouds with axes, text, HTML, interactive Plotly, Vega-Lite and Bokeh figures, and waveforms with signals over them (accurate at every zoom); filter by kind, a step slider per card, best-scalar step, configurable grid |
+| Reports | Markdown reports that embed logged items, live charts and plot snapshots; export as HTML or a zip, print to PDF |
+| Sweeps | parallel coordinates with brushing, scatter per parameter, rank correlation, best runs |
+| Timeline | runs over wall-clock time, packed concurrency view, crash, alert and artifact markers |
+| Artifacts | versions, files, metadata and a lineage graph |
+| Health alerts | NaN/Inf, loss and gradient spikes, throughput drops, per scalar and rank |
+| CLI | `nuboard up`, `demo`, `ls`, `rm`, `compact`, `merge`, `artifact add`/`ls`/`show`, `import-tensorboard` (TensorBoard logs to runs); see the [command line reference](https://eagomez2.github.io/nuboard/reference/cli/) |
+
+See the [changelog](https://eagomez2.github.io/nuboard/changelog/) and the
+[known limitations](https://eagomez2.github.io/nuboard/reference/limitations/).
+
+## Documentation
+
+The docs are a [MkDocs](https://www.mkdocs.org/) site in `docs/`:
+
+```bash
+uv run mkdocs serve    # http://localhost:8000
+```
+
+- [Installation](https://eagomez2.github.io/nuboard/installation/) and [Quickstart](https://eagomez2.github.io/nuboard/quickstart/)
+- [Logging from Python](https://eagomez2.github.io/nuboard/guide/logging/), [Using the viewer](https://eagomez2.github.io/nuboard/guide/viewer/),
+  [Sweeps](https://eagomez2.github.io/nuboard/guide/sweeps/), [Health alerts](https://eagomez2.github.io/nuboard/guide/alerts/),
+  [Artifacts and lineage](https://eagomez2.github.io/nuboard/guide/artifacts/), [Analysis API](https://eagomez2.github.io/nuboard/guide/analysis/),
+  [Distributed training](https://eagomez2.github.io/nuboard/guide/distributed/),
+  [Importing from TensorBoard](https://eagomez2.github.io/nuboard/guide/tensorboard/)
+- Reference: [query language](https://eagomez2.github.io/nuboard/reference/query/), [file format](https://eagomez2.github.io/nuboard/reference/format/),
+  [architecture](https://eagomez2.github.io/nuboard/reference/architecture/), [development](https://eagomez2.github.io/nuboard/reference/development/)
+
+## Development
+
+```bash
+uv sync                                              # Python + dev tools
+(cd frontend && pnpm install && pnpm build)          # builds the viewer into src/nuboard/static/
+uv run pytest && uv run ruff check . && uv run pyright
+(cd frontend && pnpm test && pnpm check && pnpm lint && pnpm e2e)
+uv build                                             # wheel with the frontend bundled
+```
+
+See [Development](https://eagomez2.github.io/nuboard/reference/development/) for the repository layout, the rules for
+the logging side, and how to rename the project (the name lives in three
+places).
+
+## License
+
+NuBoard is released under the [MIT License](https://github.com/eagomez2/nuboard/blob/main/LICENSE).
+
+## Requirements
+
+Python 3.10+ on Linux, macOS or Windows. It installs NumPy, PyArrow, Starlette and
+uvicorn for the viewer; logging uses only the standard library. Building the
+frontend from source needs Node 20+ and pnpm (`brew install pnpm` on macOS);
+installing from PyPI does not.

nuboard-0.20.0/README.md

@@ -0,0 +1,111 @@
+<p align="center"><img src="https://raw.githubusercontent.com/eagomez2/nuboard/main/docs/assets/logo.svg" width="72" alt=""></p>
+
+<h1 align="center">NuBoard</h1>
+
+<p align="center"><b>Experiment tracking that lives in a folder.</b><br>
+Log from Python with three calls. Every run is a folder. View thousands of runs in your browser.</p>
+
+![Charts page: a learning-rate sweep grouped by lr, mean ± std over three seeds](https://raw.githubusercontent.com/eagomez2/nuboard/main/docs/assets/charts-light.png)
+
+```python
+import nuboard as nb
+
+with nb.init("my-project", run_name="baseline", config={"lr": 3e-4}) as run:
+    for step in range(10_000):
+        loss = train_step()
+        run.add_scalar({"train/loss": loss}, step=step)  # ~3 µs, never blocks training
+```
+
+```bash
+nuboard up experiments        # http://localhost:6070
+```
+
+## Why
+
+- **No setup.** No account, no server, no database. `pip install nuboard` gives
+  you logging and the viewer; logging uses only the standard library, so it
+  adds nothing to the import time of a training script.
+- **Folder-contained.** Each run is one folder (`run.json`, an append-only
+  binary log, a media pack, a Parquet file at the end). Copy it, rsync it, zip
+  it, delete it.
+- **Fast.** Logging is a deque append; a background thread writes columnar
+  frames. The viewer reads a million points in about a tenth of a second and
+  lists thousands of runs instantly.
+- **Records what you forget.** Config, git commit and uncommitted diff,
+  installed packages, GPUs, command line, rank, console output and CPU, memory
+  and GPU use, automatically.
+- **Crash-safe.** A killed process loses at most the last second of data; torn
+  writes are ignored; crashes are marked with their traceback.
+
+## Quick start
+
+```bash
+pip install nuboard                   # or: uv pip install nuboard
+nuboard demo demo-runs --up --open    # 4 projects, 31 runs, one live run
+```
+
+Then try `where tags has "sweep" group by config.optim.lr` in the query bar and
+open the Charts page. The [quickstart](https://eagomez2.github.io/nuboard/quickstart/) has a tour, and
+[installation](https://eagomez2.github.io/nuboard/installation/) covers building from source.
+
+## What's in 0.13
+
+| Area | Included |
+| --- | --- |
+| Python API | `init` (+ resume, fork, ranks), `add_scalar`, `add_file`, `add_text`, `add_image`, `add_audio`, `add_video`, `add_figure`, `add_pr_curve`, `add_histogram`, `add_table`, `add_point_cloud`, `add_html`, `add_artifact` (copies or references), `use_artifact` (across projects), `nb.add_artifact`, `nb.get_artifact`, `finish`, context manager; system scalars (CPU, memory, GPU) and console capture |
+| Storage | documented [log format](https://eagomez2.github.io/nuboard/reference/format/), Parquet compaction with zoom levels, versioned artifacts, collections |
+| Analysis | `nb.load("project").scalars("loss", group_by="config.lr")` returns Arrow tables; properties, collections and alerts per run |
+| Runs | query language, stars, Markdown notes, archive, typed properties, tag editing, column chooser, collections, saved views, run details and config/file diffs |
+| Charts | grouped lines with bands, smoothing, zoom, linked crosshair, inspector, live updates, alerts strip, x axis by any scalar (tokens, epochs), solo or show all series |
+| Media | images, video, audio (waveform + spectrogram player with notes, or the browser's player), per-example tables compared across steps, PR curves, distributions over steps, point clouds with axes, text, HTML, interactive Plotly, Vega-Lite and Bokeh figures, and waveforms with signals over them (accurate at every zoom); filter by kind, a step slider per card, best-scalar step, configurable grid |
+| Reports | Markdown reports that embed logged items, live charts and plot snapshots; export as HTML or a zip, print to PDF |
+| Sweeps | parallel coordinates with brushing, scatter per parameter, rank correlation, best runs |
+| Timeline | runs over wall-clock time, packed concurrency view, crash, alert and artifact markers |
+| Artifacts | versions, files, metadata and a lineage graph |
+| Health alerts | NaN/Inf, loss and gradient spikes, throughput drops, per scalar and rank |
+| CLI | `nuboard up`, `demo`, `ls`, `rm`, `compact`, `merge`, `artifact add`/`ls`/`show`, `import-tensorboard` (TensorBoard logs to runs); see the [command line reference](https://eagomez2.github.io/nuboard/reference/cli/) |
+
+See the [changelog](https://eagomez2.github.io/nuboard/changelog/) and the
+[known limitations](https://eagomez2.github.io/nuboard/reference/limitations/).
+
+## Documentation
+
+The docs are a [MkDocs](https://www.mkdocs.org/) site in `docs/`:
+
+```bash
+uv run mkdocs serve    # http://localhost:8000
+```
+
+- [Installation](https://eagomez2.github.io/nuboard/installation/) and [Quickstart](https://eagomez2.github.io/nuboard/quickstart/)
+- [Logging from Python](https://eagomez2.github.io/nuboard/guide/logging/), [Using the viewer](https://eagomez2.github.io/nuboard/guide/viewer/),
+  [Sweeps](https://eagomez2.github.io/nuboard/guide/sweeps/), [Health alerts](https://eagomez2.github.io/nuboard/guide/alerts/),
+  [Artifacts and lineage](https://eagomez2.github.io/nuboard/guide/artifacts/), [Analysis API](https://eagomez2.github.io/nuboard/guide/analysis/),
+  [Distributed training](https://eagomez2.github.io/nuboard/guide/distributed/),
+  [Importing from TensorBoard](https://eagomez2.github.io/nuboard/guide/tensorboard/)
+- Reference: [query language](https://eagomez2.github.io/nuboard/reference/query/), [file format](https://eagomez2.github.io/nuboard/reference/format/),
+  [architecture](https://eagomez2.github.io/nuboard/reference/architecture/), [development](https://eagomez2.github.io/nuboard/reference/development/)
+
+## Development
+
+```bash
+uv sync                                              # Python + dev tools
+(cd frontend && pnpm install && pnpm build)          # builds the viewer into src/nuboard/static/
+uv run pytest && uv run ruff check . && uv run pyright
+(cd frontend && pnpm test && pnpm check && pnpm lint && pnpm e2e)
+uv build                                             # wheel with the frontend bundled
+```
+
+See [Development](https://eagomez2.github.io/nuboard/reference/development/) for the repository layout, the rules for
+the logging side, and how to rename the project (the name lives in three
+places).
+
+## License
+
+NuBoard is released under the [MIT License](https://github.com/eagomez2/nuboard/blob/main/LICENSE).
+
+## Requirements
+
+Python 3.10+ on Linux, macOS or Windows. It installs NumPy, PyArrow, Starlette and
+uvicorn for the viewer; logging uses only the standard library. Building the
+frontend from source needs Node 20+ and pnpm (`brew install pnpm` on macOS);
+installing from PyPI does not.

nuboard-0.20.0/benchmarks/bench.py

@@ -0,0 +1,121 @@
+"""Rough performance checks against the targets in the project brief.
+
+uv run python benchmarks/bench.py
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+import time
+from pathlib import Path
+
+import nuboard as nb
+from nuboard.catalog import Catalog
+from nuboard.reader import RunReader
+
+
+def main() -> None:
+    """Run the benchmarks and print the timings next to their targets.
+
+    Measures `Run.log` overhead, reading a live log, compacting to Parquet,
+    reading a metric from Parquet, and opening and refreshing a catalog of 5000
+    runs. Data goes to a temporary folder, removed afterwards unless `KEEP` is set.
+    """
+    root = Path(tempfile.mkdtemp())
+    data = {f"metric_{i:02d}": float(i) for i in range(50)}
+
+    run = nb.init("bench", dir=root, capture_env=False, compact=False)
+    n = 20_000
+    t0 = time.perf_counter()
+
+    for step in range(n):
+        run.add_scalar(data, step=step)
+
+    per_call = (time.perf_counter() - t0) / n
+    t1 = time.perf_counter()
+    run.finish()
+    print(f"log() of a 50-metric dict:      {per_call * 1e6:6.1f} µs per call (target < 50 µs)")
+    print(
+        f"  final flush of {n * 50 / 1e6:.1f}M points:      "
+        f"{time.perf_counter() - t1:6.2f} s (background)"
+    )
+
+    run = nb.init("bench", run_name="million", dir=root, capture_env=False, compact=False)
+
+    for step in range(100_000):
+        run.add_scalar({f"m{i}": step * 0.5 + i for i in range(10)}, step=step)
+
+    run.finish()
+    size = sum(p.stat().st_size for p in run.path.glob("events.*"))
+    t0 = time.perf_counter()
+    reader = RunReader(run.path)
+    reader.refresh()
+    total = sum(len(s[0]) for s in reader.all_scalars().values())
+    print(
+        f"read {total / 1e6:.0f}M points from the live log:   "
+        f"{time.perf_counter() - t0:6.3f} s (target < 0.1 s), "
+        f"{size / 1e6:.0f} MB on disk"
+    )
+
+    from nuboard.compact import compact_run
+
+    t0 = time.perf_counter()
+    compact_run(run.path)
+    print(
+        f"compact to Parquet:              {time.perf_counter() - t0:6.2f} s, "
+        f"{(run.path / 'data.parquet').stat().st_size / 1e6:.1f} MB"
+    )
+    reader = RunReader(run.path)
+    assert reader.parquet is not None
+    times = []
+
+    for name in ("m3", "m4", "m3"):
+        t0 = time.perf_counter()
+        reader.scalars(name)
+        times.append((time.perf_counter() - t0) * 1e3)
+
+    print(
+        f"one metric (100k points) from Parquet: first {times[0]:.1f} ms, "
+        f"warm {min(times[1:]):.1f} ms"
+    )
+
+    many = root / "many" / "proj" / "runs"
+    meta = json.dumps(
+        {
+            "format_version": 1,
+            "status": "finished",
+            "config": {"lr": 0.1},
+            "summary": {
+                f"m{i}": {"last": 1.0, "min": 0.5, "max": 2, "count": 1, "step": 0, "nonfinite": 0}
+                for i in range(20)
+            },
+        }
+    )
+
+    for i in range(5000):
+        d = many / f"20250101-0000_r{i}_aaaaaa"
+        d.mkdir(parents=True)
+        (d / "run.json").write_text(meta)
+
+    cache = root / "cache"
+    Catalog(root / "many", cache=cache).refresh()  # cold build
+    t0 = time.perf_counter()
+    cat = Catalog(root / "many", cache=cache)
+    print(f"open catalog of 5000 runs (server start): {(time.perf_counter() - t0) * 1e3:5.0f} ms")
+    t0 = time.perf_counter()
+    cat.refresh()
+    print(
+        f"refresh + list {len(cat.runs())} runs (per request): "
+        f"{(time.perf_counter() - t0) * 1e3:5.0f} ms (target < 200 ms)"
+    )
+
+    if os.environ.get("KEEP") is None:
+        import shutil
+
+        shutil.rmtree(root, ignore_errors=True)
+
+
+if __name__ == "__main__":
+    main()