runboard-ml 0.2.0__tar.gz

runboard_ml-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alperen Toker
+
+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.

runboard_ml-0.2.0/PKG-INFO

@@ -0,0 +1,187 @@
+Metadata-Version: 2.4
+Name: runboard-ml
+Version: 0.2.0
+Summary: Pre-registered ML experiments: lock the plan, run on your GPU, Kaggle, SSH or SLURM, watch live, and get hypotheses decided with bootstrap intervals and paper-ready output.
+Author: Alperen Toker
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/alperentoker/runboard-ml
+Project-URL: Documentation, https://github.com/alperentoker/runboard-ml/blob/main/docs/manifest.md
+Project-URL: Issues, https://github.com/alperentoker/runboard-ml/issues
+Project-URL: Security, https://github.com/alperentoker/runboard-ml/security/policy
+Keywords: pre-registration,reproducibility,hypothesis testing,bootstrap,machine learning,training,dashboard,kaggle,slurm,yolo
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+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 :: Information Analysis
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi>=0.110
+Requires-Dist: uvicorn>=0.29
+Requires-Dist: pyyaml>=6
+Provides-Extra: kaggle
+Requires-Dist: kaggle>=2.2; extra == "kaggle"
+Requires-Dist: six; extra == "kaggle"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: httpx; extra == "dev"
+Requires-Dist: kaggle>=2.2; extra == "dev"
+Requires-Dist: six; extra == "dev"
+Requires-Dist: numpy; extra == "dev"
+Dynamic: license-file
+
+# runboard
+
+**Pre-registered machine-learning experiments, from the plan to the paper.** Write your questions and hypotheses,
+lock the plan, run the experiments on your own GPU, Kaggle, a machine over SSH or a SLURM cluster, watch them live, and
+get every hypothesis decided with a bootstrap confidence interval, plus the tables, methods and deviations sections
+for the paper. One self-hosted dashboard for all your projects; everything stays in readable files in your repository.
+
+**New here?** `pip install runboard-ml numpy`, then `runboard demo`: a five-minute pre-registered study on any CPU,
+walked through in the [tutorial](https://github.com/alperentoker/runboard-ml/blob/main/docs/tutorial.md).
+
+[Türkçe](https://github.com/alperentoker/runboard-ml/blob/main/README.tr.md) · [![tests](https://github.com/alperentoker/runboard-ml/actions/workflows/tests.yml/badge.svg)](https://github.com/alperentoker/runboard-ml/actions/workflows/tests.yml)
+
+![Hypotheses decided with confidence intervals](https://raw.githubusercontent.com/alperentoker/runboard-ml/main/docs/images/tutorial-7-verdicts.png)
+
+<table><tr>
+<td width="50%">
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/alperentoker/runboard-ml/main/docs/images/run-dark.png">
+  <img alt="A run's page: live progress, results and training curves" src="https://raw.githubusercontent.com/alperentoker/runboard-ml/main/docs/images/run-light.png">
+</picture>
+
+<sub>A run, live</sub>
+</td>
+<td width="50%">
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/alperentoker/runboard-ml/main/docs/images/plan-dark.png">
+  <img alt="Editing the run plan: every change is previewed as the lines it changes" src="https://raw.githubusercontent.com/alperentoker/runboard-ml/main/docs/images/plan-light.png">
+</picture>
+
+<sub>Editing the plan: a preview of the exact lines that change</sub>
+</td>
+</tr></table>
+
+- **Hypotheses a machine can check** — `R7.aerial >= 0.9 * R5.aerial`, `collapse(R4, ground, aerial) > ...`, seed groups,
+  `log_fit(...)`: each comparison is decided on paired bootstrap replicates as *supported*, *refuted* or
+  *indistinguishable*, with its 95 % interval.
+- **A lock that means something** — `plan.lock.json` records when, at which commit and the fingerprints of the plan,
+  the runs and the scripts; every later change needs a reason and is listed as a deviation. A sealed test set is
+  evaluated once per model, on the record.
+- **Research wizard** — questions, experiment designs (specialists, data-size curves, architectures, ablations,
+  seeds), the evaluation protocol and hypotheses checked as you type become a ready project.
+- **Code templates** — split, leakage check, conversion, data-size subsets, evaluation and speed scripts, written into
+  your project as ordinary files that runboard never overwrites once you change them.
+- **Paper output** — Markdown and LaTeX tables, the hypotheses, a methods draft, the deviations section, a
+  reproducibility checklist, a registered-report page and an archive for Zenodo.
+- **Live runs anywhere** — your GPU, Kaggle (private kernels, weekly quota, private datasets), a machine over SSH and a
+  SLURM cluster (your own SSH keys; runboard never sees a password); logs, second-by-second progress, charts, a queue.
+- **Provenance** — every run records the commit, uncommitted changes and the fingerprints of what it started from.
+- **Tablet view**, a Code page, English and Türkçe.
+
+Secrets never leave your machine: the Kaggle token stays in `~/.kaggle`, paired devices and all state live in
+`~/.runboard`, never inside a project repository.
+
+## Install
+
+```bash
+pip install runboard-ml            # or: pip install "runboard-ml[kaggle]" for Kaggle
+runboard                           # http://localhost:8000 — this computer only, no password
+```
+
+The package is called `runboard-ml` on PyPI (`runboard` belongs to another project); the command and the Python module
+are `runboard`. Do not install both in one environment: they would share the module name. Python 3.11 or newer.
+
+Then, in the dashboard:
+
+1. **System → Connections → Kaggle** (only if you want cloud GPUs): the panel walks you through creating a token on
+   kaggle.com and pasting it once. It is saved to `~/.kaggle/access_token` on this machine, tested, and never shown again.
+2. **New project**: pick a folder and choose *Pre-registered study (YOLO)*, *YOLO training (no code)* or *My own training
+   script*, then where to run (this computer, Kaggle, SSH, SLURM). runboard writes `runboard.yaml`, the runs file and,
+   for YOLO, the training and evaluation scripts into the folder; it never changes your own files.
+
+A folder that already has a `runboard.yaml` can be added from the same wizard or with `runboard add PATH`.
+
+## Tablet access
+
+By default runboard listens only on this computer (`127.0.0.1`) and asks for nothing. To follow runs from a tablet on
+the same Wi-Fi, turn on **System → Tablet access** (the dashboard restarts on all network interfaces), press
+**Pair a device** and scan the QR code with the tablet, or open the address shown and type the 6-digit code. The code
+works once and for two minutes. Paired devices are listed there and can be removed at any time.
+
+A paired device can follow, start and stop runs. Entering the Kaggle token, adding projects, changing code and the
+project file, the folder browser and startup settings stay on this computer. Outside your home network, use a VPN such
+as Tailscale and add its machine name to `allowed_hosts` in `~/.runboard/config.yaml`. See
+[SECURITY.md](https://github.com/alperentoker/runboard-ml/blob/main/SECURITY.md).
+
+## A project by hand
+
+The wizard covers the common cases. Under the hood a project is any folder with a `runboard.yaml` (and, for a
+pre-registered study, a `plan.yaml`). runboard does not own your code or configs; the manifest just tells it where
+things are:
+
+```yaml
+version: 2
+name: My detector
+runs:
+  file: configs/runs.yaml          # your runs, in your own format: a mapping of run id -> fields
+  section: runs
+  defaults: train
+  name: "{id}-{model|stem}-s{seed}"
+backends:
+  local:  {command: '"{python}" train.py --run {id}', output_dir: runs/local}
+  kaggle: {files: {train.py: train.py, runs.yaml: configs/runs.yaml}, command: "python train.py --run {id}"}
+results:
+  report: "{out}/summary.json"
+  metrics: {primary: map50_95}
+```
+
+See [the manifest reference](https://github.com/alperentoker/runboard-ml/blob/main/docs/manifest.md) for every option,
+including `plan.yaml`, criteria, evaluation files, the lock and the backends, and
+[the design notes](https://github.com/alperentoker/runboard-ml/blob/main/docs/design-v2.md) for how verdicts are
+computed.
+
+## Reporting progress
+
+Print one line per event from your training script, or use `rb.py` (stdlib only; `runboard demo` and the wizard put a
+copy next to your scripts):
+
+```python
+import rb
+rb.ultralytics(model)            # Ultralytics: one line adds everything below
+rb.start(epochs=100, batches=798)
+rb.beat(epoch=3, batch=400, batches=798, its=4.9)
+rb.epoch(3, epochs=100, secs=171, metrics={"map": 48.2}, best=48.2, eta=time.time() + 3600)
+```
+
+Each call prints `@@rb {json}`; your own log lines are untouched. Projects with existing plain-text logs can describe
+them with regular expressions instead (`progress.patterns`).
+
+## Run it permanently
+
+*System → Start runboard when Windows starts* (Windows), or a systemd/launchd service running `runboard serve`.
+`runboard serve` also starts a small watchdog: if the dashboard stops answering for 20 s it is started again, and every
+start, stop and unexpected error is written with its time to `~/.runboard/server.log`. `runboard stop` stops both and
+keeps them stopped until the next `runboard serve` (set `watchdog: false` in `~/.runboard/config.yaml` to go without).
+To reach it from outside your home network, put it behind a private network such as Tailscale rather than exposing the port.
+
+## Development
+
+```bash
+git clone https://github.com/alperentoker/runboard-ml
+cd runboard-ml
+pip install -e .[dev]
+pytest
+```
+
+MIT licensed. Changes: [CHANGELOG.md](https://github.com/alperentoker/runboard-ml/blob/main/CHANGELOG.md) ·
+plans: [ROADMAP.md](https://github.com/alperentoker/runboard-ml/blob/main/ROADMAP.md).

runboard_ml-0.2.0/README.md

@@ -0,0 +1,149 @@
+# runboard
+
+**Pre-registered machine-learning experiments, from the plan to the paper.** Write your questions and hypotheses,
+lock the plan, run the experiments on your own GPU, Kaggle, a machine over SSH or a SLURM cluster, watch them live, and
+get every hypothesis decided with a bootstrap confidence interval, plus the tables, methods and deviations sections
+for the paper. One self-hosted dashboard for all your projects; everything stays in readable files in your repository.
+
+**New here?** `pip install runboard-ml numpy`, then `runboard demo`: a five-minute pre-registered study on any CPU,
+walked through in the [tutorial](https://github.com/alperentoker/runboard-ml/blob/main/docs/tutorial.md).
+
+[Türkçe](https://github.com/alperentoker/runboard-ml/blob/main/README.tr.md) · [![tests](https://github.com/alperentoker/runboard-ml/actions/workflows/tests.yml/badge.svg)](https://github.com/alperentoker/runboard-ml/actions/workflows/tests.yml)
+
+![Hypotheses decided with confidence intervals](https://raw.githubusercontent.com/alperentoker/runboard-ml/main/docs/images/tutorial-7-verdicts.png)
+
+<table><tr>
+<td width="50%">
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/alperentoker/runboard-ml/main/docs/images/run-dark.png">
+  <img alt="A run's page: live progress, results and training curves" src="https://raw.githubusercontent.com/alperentoker/runboard-ml/main/docs/images/run-light.png">
+</picture>
+
+<sub>A run, live</sub>
+</td>
+<td width="50%">
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/alperentoker/runboard-ml/main/docs/images/plan-dark.png">
+  <img alt="Editing the run plan: every change is previewed as the lines it changes" src="https://raw.githubusercontent.com/alperentoker/runboard-ml/main/docs/images/plan-light.png">
+</picture>
+
+<sub>Editing the plan: a preview of the exact lines that change</sub>
+</td>
+</tr></table>
+
+- **Hypotheses a machine can check** — `R7.aerial >= 0.9 * R5.aerial`, `collapse(R4, ground, aerial) > ...`, seed groups,
+  `log_fit(...)`: each comparison is decided on paired bootstrap replicates as *supported*, *refuted* or
+  *indistinguishable*, with its 95 % interval.
+- **A lock that means something** — `plan.lock.json` records when, at which commit and the fingerprints of the plan,
+  the runs and the scripts; every later change needs a reason and is listed as a deviation. A sealed test set is
+  evaluated once per model, on the record.
+- **Research wizard** — questions, experiment designs (specialists, data-size curves, architectures, ablations,
+  seeds), the evaluation protocol and hypotheses checked as you type become a ready project.
+- **Code templates** — split, leakage check, conversion, data-size subsets, evaluation and speed scripts, written into
+  your project as ordinary files that runboard never overwrites once you change them.
+- **Paper output** — Markdown and LaTeX tables, the hypotheses, a methods draft, the deviations section, a
+  reproducibility checklist, a registered-report page and an archive for Zenodo.
+- **Live runs anywhere** — your GPU, Kaggle (private kernels, weekly quota, private datasets), a machine over SSH and a
+  SLURM cluster (your own SSH keys; runboard never sees a password); logs, second-by-second progress, charts, a queue.
+- **Provenance** — every run records the commit, uncommitted changes and the fingerprints of what it started from.
+- **Tablet view**, a Code page, English and Türkçe.
+
+Secrets never leave your machine: the Kaggle token stays in `~/.kaggle`, paired devices and all state live in
+`~/.runboard`, never inside a project repository.
+
+## Install
+
+```bash
+pip install runboard-ml            # or: pip install "runboard-ml[kaggle]" for Kaggle
+runboard                           # http://localhost:8000 — this computer only, no password
+```
+
+The package is called `runboard-ml` on PyPI (`runboard` belongs to another project); the command and the Python module
+are `runboard`. Do not install both in one environment: they would share the module name. Python 3.11 or newer.
+
+Then, in the dashboard:
+
+1. **System → Connections → Kaggle** (only if you want cloud GPUs): the panel walks you through creating a token on
+   kaggle.com and pasting it once. It is saved to `~/.kaggle/access_token` on this machine, tested, and never shown again.
+2. **New project**: pick a folder and choose *Pre-registered study (YOLO)*, *YOLO training (no code)* or *My own training
+   script*, then where to run (this computer, Kaggle, SSH, SLURM). runboard writes `runboard.yaml`, the runs file and,
+   for YOLO, the training and evaluation scripts into the folder; it never changes your own files.
+
+A folder that already has a `runboard.yaml` can be added from the same wizard or with `runboard add PATH`.
+
+## Tablet access
+
+By default runboard listens only on this computer (`127.0.0.1`) and asks for nothing. To follow runs from a tablet on
+the same Wi-Fi, turn on **System → Tablet access** (the dashboard restarts on all network interfaces), press
+**Pair a device** and scan the QR code with the tablet, or open the address shown and type the 6-digit code. The code
+works once and for two minutes. Paired devices are listed there and can be removed at any time.
+
+A paired device can follow, start and stop runs. Entering the Kaggle token, adding projects, changing code and the
+project file, the folder browser and startup settings stay on this computer. Outside your home network, use a VPN such
+as Tailscale and add its machine name to `allowed_hosts` in `~/.runboard/config.yaml`. See
+[SECURITY.md](https://github.com/alperentoker/runboard-ml/blob/main/SECURITY.md).
+
+## A project by hand
+
+The wizard covers the common cases. Under the hood a project is any folder with a `runboard.yaml` (and, for a
+pre-registered study, a `plan.yaml`). runboard does not own your code or configs; the manifest just tells it where
+things are:
+
+```yaml
+version: 2
+name: My detector
+runs:
+  file: configs/runs.yaml          # your runs, in your own format: a mapping of run id -> fields
+  section: runs
+  defaults: train
+  name: "{id}-{model|stem}-s{seed}"
+backends:
+  local:  {command: '"{python}" train.py --run {id}', output_dir: runs/local}
+  kaggle: {files: {train.py: train.py, runs.yaml: configs/runs.yaml}, command: "python train.py --run {id}"}
+results:
+  report: "{out}/summary.json"
+  metrics: {primary: map50_95}
+```
+
+See [the manifest reference](https://github.com/alperentoker/runboard-ml/blob/main/docs/manifest.md) for every option,
+including `plan.yaml`, criteria, evaluation files, the lock and the backends, and
+[the design notes](https://github.com/alperentoker/runboard-ml/blob/main/docs/design-v2.md) for how verdicts are
+computed.
+
+## Reporting progress
+
+Print one line per event from your training script, or use `rb.py` (stdlib only; `runboard demo` and the wizard put a
+copy next to your scripts):
+
+```python
+import rb
+rb.ultralytics(model)            # Ultralytics: one line adds everything below
+rb.start(epochs=100, batches=798)
+rb.beat(epoch=3, batch=400, batches=798, its=4.9)
+rb.epoch(3, epochs=100, secs=171, metrics={"map": 48.2}, best=48.2, eta=time.time() + 3600)
+```
+
+Each call prints `@@rb {json}`; your own log lines are untouched. Projects with existing plain-text logs can describe
+them with regular expressions instead (`progress.patterns`).
+
+## Run it permanently
+
+*System → Start runboard when Windows starts* (Windows), or a systemd/launchd service running `runboard serve`.
+`runboard serve` also starts a small watchdog: if the dashboard stops answering for 20 s it is started again, and every
+start, stop and unexpected error is written with its time to `~/.runboard/server.log`. `runboard stop` stops both and
+keeps them stopped until the next `runboard serve` (set `watchdog: false` in `~/.runboard/config.yaml` to go without).
+To reach it from outside your home network, put it behind a private network such as Tailscale rather than exposing the port.
+
+## Development
+
+```bash
+git clone https://github.com/alperentoker/runboard-ml
+cd runboard-ml
+pip install -e .[dev]
+pytest
+```
+
+MIT licensed. Changes: [CHANGELOG.md](https://github.com/alperentoker/runboard-ml/blob/main/CHANGELOG.md) ·
+plans: [ROADMAP.md](https://github.com/alperentoker/runboard-ml/blob/main/ROADMAP.md).

runboard_ml-0.2.0/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "runboard-ml"  # "runboard" on PyPI belongs to another project; the command and the module are still runboard
+version = "0.2.0"
+description = "Pre-registered ML experiments: lock the plan, run on your GPU, Kaggle, SSH or SLURM, watch live, and get hypotheses decided with bootstrap intervals and paper-ready output."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Alperen Toker" }]
+requires-python = ">=3.11"  # the Kaggle client (kaggle>=2.2) needs 3.11
+dependencies = ["fastapi>=0.110", "uvicorn>=0.29", "pyyaml>=6"]
+keywords = ["pre-registration", "reproducibility", "hypothesis testing", "bootstrap", "machine learning", "training",
+            "dashboard", "kaggle", "slurm", "yolo"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Environment :: Web Environment",
+  "Intended Audience :: Science/Research",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+  "Topic :: Scientific/Engineering :: Information Analysis",
+]
+
+[project.urls]
+Homepage = "https://github.com/alperentoker/runboard-ml"
+Documentation = "https://github.com/alperentoker/runboard-ml/blob/main/docs/manifest.md"
+Issues = "https://github.com/alperentoker/runboard-ml/issues"
+Security = "https://github.com/alperentoker/runboard-ml/security/policy"
+
+[project.optional-dependencies]
+kaggle = ["kaggle>=2.2", "six"]  # newer Kaggle clients import six without depending on it
+dev = ["pytest", "httpx", "kaggle>=2.2", "six", "numpy"]  # numpy: the demo and the evaluation helpers
+
+[project.scripts]
+runboard = "runboard.cli:main"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.setuptools.packages.find]
+include = ["runboard*"]
+
+[tool.setuptools.package-data]
+runboard = ["static/*", "static/js/*", "templates/*", "demo/*"]

runboard_ml-0.2.0/runboard/__init__.py

@@ -0,0 +1,2 @@
+"""runboard: one self-hosted dashboard for ML training runs across projects and compute backends."""
+__version__ = "0.2.0"

runboard_ml-0.2.0/runboard/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

runboard_ml-0.2.0/runboard/access.py

@@ -0,0 +1,219 @@
+"""Who may use the dashboard.
+
+- This computer (a loopback connection) needs nothing: no password, no login screen.
+- Other devices (a tablet on the same Wi-Fi) only when network access is switched on, and only after pairing once:
+  this computer shows a QR code / 6-digit code, the device gets a long random key in a cookie, and only a hash of that
+  key is stored (~/.runboard/devices.json). Paired devices can be removed at any time.
+- Every request is also checked against DNS rebinding (Host header) and cross-site requests (Origin), so a web page
+  open in a browser cannot drive the dashboard.
+"""
+from __future__ import annotations
+
+import copy
+import hashlib
+import ipaddress
+import secrets
+import socket
+import threading
+import time
+from http.cookies import SimpleCookie
+
+from . import home
+
+COOKIE = "rb_device"
+PAIR_SECONDS = 120
+PAIR_TRIES = 5
+_lock = threading.Lock()
+_pairing: dict | None = None
+
+
+# ---------------------------------------------------------------- devices
+
+def _devices_file():
+    return home.HOME / "devices.json"
+
+
+_devices_cache: tuple = (None, [])
+
+
+def devices() -> list[dict]:
+    """Paired devices; every request from a tablet asks, so the file is read again only when it changed."""
+    global _devices_cache
+    f = _devices_file()
+    try:
+        st = f.stat()
+        sig = (str(f), st.st_mtime_ns, st.st_size)
+    except FileNotFoundError:
+        return []
+    if _devices_cache[0] != sig:
+        _devices_cache = (sig, home.read_json(f, []))
+    return copy.deepcopy(_devices_cache[1])
+
+
+def _hash(key: str) -> str:
+    return hashlib.sha256(key.encode()).hexdigest()
+
+
+def add_device(name: str) -> str:
+    """Creates a device and returns its cookie value (the key itself is never stored)."""
+    did, key = secrets.token_hex(4), secrets.token_urlsafe(32)
+    with _lock:
+        ds = devices()
+        ds.append({"id": did, "name": name[:60] or "device", "hash": _hash(key),
+                   "created": time.strftime("%Y-%m-%d %H:%M"), "last_seen": None})
+        home.write_json(_devices_file(), ds)
+    return f"{did}.{key}"
+
+
+def remove_device(did: str) -> bool:
+    with _lock:
+        ds = devices()
+        keep = [d for d in ds if d["id"] != did]
+        home.write_json(_devices_file(), keep)
+    return len(keep) != len(ds)
+
+
+def device_for(cookie_value: str | None) -> dict | None:
+    if not cookie_value or "." not in cookie_value:
+        return None
+    did, key = cookie_value.split(".", 1)
+    h = _hash(key)
+    for d in devices():
+        if d["id"] == did and secrets.compare_digest(d["hash"], h):
+            if not d.get("last_seen") or d["last_seen"][:16] != time.strftime("%Y-%m-%d %H:%M"):
+                with _lock:
+                    ds = devices()
+                    for x in ds:
+                        if x["id"] == did:
+                            x["last_seen"] = time.strftime("%Y-%m-%d %H:%M")
+                    home.write_json(_devices_file(), ds)
+            return d
+    return None
+
+
+def device_name(user_agent: str) -> str:
+    ua = user_agent or ""
+    for key, name in (("iPad", "iPad"), ("iPhone", "iPhone"), ("Android", "Android"), ("Macintosh", "Mac"),
+                      ("Windows", "Windows"), ("Linux", "Linux")):
+        if key in ua:
+            return name + (" tablet" if key == "Android" and "Mobile" not in ua else "")
+    return "device"
+
+
+# ---------------------------------------------------------------- pairing
+
+def start_pairing() -> dict:
+    """A new one-time pairing: a token for the QR link and a 6-digit code to type by hand. The previous one ends."""
+    global _pairing
+    with _lock:
+        _pairing = {"token": secrets.token_urlsafe(16), "code": f"{secrets.randbelow(10**6):06d}",
+                    "expires": time.time() + PAIR_SECONDS, "tries": 0}
+        return dict(_pairing)
+
+
+def redeem(token: str | None = None, code: str | None = None) -> bool:
+    """True once for the current pairing's token or code; wrong codes count, and after PAIR_TRIES it is void."""
+    global _pairing
+    with _lock:
+        p = _pairing
+        if not p or time.time() > p["expires"]:
+            _pairing = None
+            return False
+        ok = (token is not None and secrets.compare_digest(token, p["token"])) or \
+             (code is not None and secrets.compare_digest(str(code).strip(), p["code"]))
+        if ok:
+            _pairing = None
+            return True
+        p["tries"] += 1
+        if p["tries"] >= PAIR_TRIES:
+            _pairing = None
+        return False
+
+
+def pairing_state() -> dict | None:
+    p = _pairing
+    return {"seconds": max(0, round(p["expires"] - time.time()))} if p and time.time() < p["expires"] else None
+
+
+# ---------------------------------------------------------------- request checks
+
+def _local_addresses() -> set[str]:
+    out = {"127.0.0.1", "::1"}
+    try:
+        out.update(socket.gethostbyname_ex(socket.gethostname())[2])
+    except OSError:
+        pass
+    return out
+
+
+LOCAL_ADDRESSES = _local_addresses()
+
+
+def is_local_client(host: str | None) -> bool:
+    if not host:
+        return False
+    host = host.removeprefix("::ffff:")
+    return host in LOCAL_ADDRESSES or host.startswith("127.")
+
+
+def host_allowed(host_header: str, extra: list[str]) -> bool:
+    """DNS rebinding guard: a request must name this machine by IP, as localhost, by its own name or by a name listed
+    in config.yaml (allowed_hosts, e.g. a Tailscale name). A web page's own domain is never accepted."""
+    host = host_header.strip().lower()
+    if host.startswith("["):
+        host = host[1:host.find("]")]
+    elif host.count(":") == 1:
+        host = host.split(":")[0]
+    try:
+        ipaddress.ip_address(host)
+        return True
+    except ValueError:
+        pass
+    names = {"localhost", socket.gethostname().lower()} | {h.lower() for h in extra}
+    return host in names or host.endswith(".localhost")
+
+
+def cross_site(method: str, headers: dict[str, str]) -> bool:
+    """CSRF guard for anything that changes state: another site's page may not send it."""
+    if method in ("GET", "HEAD", "OPTIONS"):
+        return False
+    if headers.get("sec-fetch-site", "same-origin") not in ("same-origin", "none"):
+        return True
+    origin = headers.get("origin")
+    if origin and origin != "null":
+        return origin.split("://", 1)[-1].lower() != headers.get("host", "").lower()
+    return origin == "null"
+
+
+def cookie_value(headers: dict[str, str]) -> str | None:
+    c = SimpleCookie()
+    try:
+        c.load(headers.get("cookie", ""))
+    except Exception:
+        return None
+    return c[COOKIE].value if COOKIE in c else None
+
+
+def set_cookie_header(value: str) -> str:
+    return f"{COOKIE}={value}; Path=/; Max-Age=31536000; HttpOnly; SameSite=Strict"
+
+
+CSP = ("default-src 'self'; script-src 'self'{scripts}; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob:; "
+       "media-src 'self' blob:; connect-src 'self'; frame-ancestors 'none'; base-uri 'none'; form-action 'self'")
+SECURITY_HEADERS = [
+    (b"x-frame-options", b"DENY"),
+    (b"x-content-type-options", b"nosniff"),
+    (b"referrer-policy", b"no-referrer"),
+    (b"content-security-policy", CSP.format(scripts="").encode()),
+]
+
+
+def page_csp(html: str) -> str:
+    """The policy for one page: only the page's own scripts run, named by their SHA-256. A script that got into the page
+    any other way (an injected tag or an onclick attribute) is refused by the browser."""
+    import base64
+    import re
+    hashes = [base64.b64encode(hashlib.sha256(m.encode("utf-8")).digest()).decode()
+              for m in re.findall(r"<script>(.*?)</script>", html, re.S)]
+    return CSP.format(scripts="".join(f" 'sha256-{h}'" for h in hashes))
+

runboard_ml-0.2.0/runboard/backends/__init__.py

@@ -0,0 +1,12 @@
+"""Compute backends. Each one launches a run, reports its status, streams its log and brings its outputs home.
+
+Adding a backend: subclass Backend in a new module and register it in BACKENDS.
+"""
+from .base import ACTIVE, DONE, Backend
+from .kaggle import KaggleBackend
+from .local import LocalBackend
+from .remote import SlurmBackend, SSHBackend
+
+BACKENDS: dict[str, Backend] = {b.name: b for b in (KaggleBackend(), LocalBackend(), SSHBackend(), SlurmBackend())}
+
+__all__ = ["ACTIVE", "DONE", "Backend", "BACKENDS"]