tuff-rl 0.1.0__py3-none-any.whl

tuff_rl-0.1.0.dist-info/METADATA

@@ -0,0 +1,171 @@
+Metadata-Version: 2.4
+Name: tuff-rl
+Version: 0.1.0
+Summary: Training logs as TensorBoard event files, and a live board that follows them
+Author: TalexDreamSoul
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/talex-touch/tuff-rl
+Project-URL: Repository, https://github.com/talex-touch/tuff-rl
+Project-URL: Issues, https://github.com/talex-touch/tuff-rl/issues
+Project-URL: Changelog, https://github.com/talex-touch/tuff-rl/blob/main/CHANGELOG.md
+Keywords: reinforcement-learning,tensorboard,tfevents,experiment-tracking,training-dashboard,machine-learning
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+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
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: system
+Requires-Dist: psutil>=5.9; extra == "system"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: tensorboard>=2.15; extra == "dev"
+Requires-Dist: tensorboardX>=2.6; extra == "dev"
+Dynamic: license-file
+
+# tuff-rl
+
+**Training logs as TensorBoard event files, and a live board that follows them.**
+
+[English](https://github.com/talex-touch/tuff-rl/blob/main/README.md) · [简体中文](https://github.com/talex-touch/tuff-rl/blob/main/README.zh.md)
+
+[![PyPI](https://img.shields.io/pypi/v/tuff-rl)](https://pypi.org/project/tuff-rl/)
+[![Python](https://img.shields.io/pypi/pyversions/tuff-rl)](https://pypi.org/project/tuff-rl/)
+[![CI](https://github.com/talex-touch/tuff-rl/actions/workflows/ci.yml/badge.svg)](https://github.com/talex-touch/tuff-rl/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](https://github.com/talex-touch/tuff-rl/blob/main/LICENSE)
+
+![The board following six CartPole runs while they train](https://raw.githubusercontent.com/talex-touch/tuff-rl/main/docs/images/board-live.gif)
+
+One call in a training script writes everything about the run into TensorBoard event files
+under `logs/`: the metrics, the config, what the script prints, and the CPU, memory and GPU
+it used. The same call starts a board in your browser that follows those files as they grow.
+`tensorboard --logdir logs` opens the same files, and the board opens directories that
+TensorBoard, tensorboardX or PyTorch wrote. The package has no dependencies.
+
+## Install
+
+```bash
+pip install tuff-rl
+pip install "tuff-rl[system]"   # adds CPU and memory metrics, through psutil
+```
+
+## Quick start
+
+```python
+import tuffrl
+
+run = tuffrl.init(logdir="logs", group="cartpole/lr-0.5", name="seed-0", config={"lr": 0.5, "gamma": 0.99})
+for step in range(10_000):
+    ...
+    run.log({"train": {"loss": loss, "return": episode_return}}, step=step)
+run.finish()
+```
+
+The first script to start opens the board at <http://127.0.0.1:6066>; scripts started later
+join it, so a sweep of many processes shares one board. A run that ends with an exception is
+marked failed, and one stopped with Ctrl-C is marked stopped. Under `torch.distributed`, only
+rank 0 starts the board.
+
+Code that already uses PyTorch's `SummaryWriter` changes only its import:
+
+```python
+from tuffrl import SummaryWriter
+```
+
+The shim covers `add_scalar`, `add_scalars`, `add_text`, `add_hparams`, `flush` and `close`.
+
+## Try the demo
+
+```bash
+pip install "tuff-rl[system]"
+curl -O https://raw.githubusercontent.com/talex-touch/tuff-rl/main/examples/cartpole.py
+python cartpole.py
+```
+
+REINFORCE on CartPole in plain Python: two learning rates, three seeds each, six processes
+in parallel. It takes about 35 seconds.
+
+## The board
+
+| | |
+| --- | --- |
+| ![Two learning rates, each drawn as the mean of three seeds with a band for their spread](https://raw.githubusercontent.com/talex-touch/tuff-rl/main/docs/images/board-groups.png) | ![The config of six runs side by side, with the two differing keys marked](https://raw.githubusercontent.com/talex-touch/tuff-rl/main/docs/images/board-config.png) |
+| Runs in one directory form a group. Merged, a group is drawn as its mean with a band for the spread of its runs. | The config of every run side by side, with the keys that differ marked. |
+| ![The printed output of one run, with stderr in red](https://raw.githubusercontent.com/talex-touch/tuff-rl/main/docs/images/board-output.png) | ![CPU and memory charts for the runs](https://raw.githubusercontent.com/talex-touch/tuff-rl/main/docs/images/board-system.png) |
+| What each run printed, stdout and stderr in order, searchable, following new lines. | CPU and memory of the training machine and process, and the GPUs that `nvidia-smi` reports. |
+
+Charts smooth with an exponential moving average and can also show the raw values and a log
+x-axis. Drag across a chart to zoom in, and double-click it to zoom back out. The board
+follows the system's light or dark theme.
+
+## Training on another machine
+
+Over SSH the board starts on the training machine and does not open a browser. Instead it
+prints the command that forwards its port to your own machine:
+
+```text
+[tuffrl] board: http://127.0.0.1:6066  (logdir /data/logs)
+[tuffrl] from your own machine: ssh -N -L 6066:127.0.0.1:6066 you@gpu-box  then open http://127.0.0.1:6066
+```
+
+The board has no login. It listens on 127.0.0.1 unless `TUFFRL_BOARD_HOST` says otherwise;
+listening on another address shows your logs and config to anyone who can reach that port.
+
+## Command line and settings
+
+```bash
+tuff-rl board logs   # serve a log directory, including one TensorBoard wrote
+tuff-rl stop logs    # stop the board serving it
+```
+
+| Variable | Effect |
+| --- | --- |
+| `TUFFRL_BOARD=0` | Training scripts do not start the board. |
+| `TUFFRL_OPEN_BROWSER=0` | The board starts but no browser opens. |
+| `TUFFRL_BOARD_PORT` | Port to try first (default 6066); the next free one is used when it is taken. |
+| `TUFFRL_BOARD_HOST` | Address to listen on (default 127.0.0.1). |
+
+## How it works
+
+- **Event files.** The writer frames records the way TFRecord does (length, CRC32C, data,
+  CRC32C) and encodes the `Event` and `Summary` protobufs by hand, so neither TensorFlow nor
+  protobuf is needed. Metrics are scalar summaries, printed output uses the text plugin, and
+  the config is an HParams session, so TensorBoard's HParams tab lists the runs and groups
+  them by `group`.
+- **The board.** A standard-library HTTP server reads each event file from where it stopped,
+  and the page receives a snapshot followed by a stream of new points (server-sent events).
+  The page is a Vue app built on [TuffEx](https://www.npmjs.com/package/@talex-touch/tuffex)
+  and ships inside the wheel.
+- **One board per log directory.** `logs/.tuffrl/board.json` records which board serves the
+  directory. Scripts starting at the same moment agree on one of them to launch it, and the
+  board keeps running after training ends until `tuff-rl stop`.
+
+## Status
+
+0.1 is an alpha. The board reads images and audio but does not show them yet; that and the
+rest of the plan are in the [roadmap issues](https://github.com/talex-touch/tuff-rl/issues?q=is%3Aissue+label%3Aroadmap).
+
+## Development
+
+```bash
+cd web && pnpm install && pnpm build && cd ..   # builds the board page into src/tuffrl/board/static
+pip install -e ".[dev,system]"
+python -m pytest
+uvx ruff check .
+```
+
+See [CONTRIBUTING.md](https://github.com/talex-touch/tuff-rl/blob/main/CONTRIBUTING.md) for the rest, including how a release is made.
+
+## License
+
+[MIT](https://github.com/talex-touch/tuff-rl/blob/main/LICENSE)

tuff_rl-0.1.0.dist-info/RECORD

@@ -0,0 +1,31 @@
+tuff_rl-0.1.0.dist-info/licenses/LICENSE,sha256=oSD0uISEueTD8yCbTYFq8NeTxuNPvuzoFK0t0-xbKG0,1081
+tuffrl/__init__.py,sha256=STyyLLCc4_S6-Q_wGbQieMmYBJbaVKhBCwzDEdjCit0,1630
+tuffrl/__main__.py,sha256=k1ocEWawweo1qCJWNFAAvyxz3tcY13dzvCenHszij30,48
+tuffrl/cli.py,sha256=1UhKuh8v5XDVnn2es3snWUlMdTkzRz3s7b2smIq6t4g,1878
+tuffrl/compat.py,sha256=NOFxT45hgd_Ip6TDQVPA114AYbNAFuxys58BFZTdQyQ,3540
+tuffrl/run.py,sha256=wdB9hChZYEt0ISz9YNCixeGlGu3J6PU6v96knS_icZ4,6722
+tuffrl/board/__init__.py,sha256=oj1U1KWPEkHNByXUoHyaaX6o-KB7aupP7BcCEZTxNck,176
+tuffrl/board/launch.py,sha256=meUOBf58v4cyM1fcPmWlj-cbCUtF4L_PplpdcBiJ6yU,5019
+tuffrl/board/lock.py,sha256=3DRYuIzblG0JuBNa_NmlqhL2T2fm6n5IPs2qBtpv99E,1175
+tuffrl/board/server.py,sha256=DFNteLduy-qIarOHn_5vieLesw3AyNfOo2vx-AIpOaw,7895
+tuffrl/board/store.py,sha256=6z6nmDWigbgZtFFM-YO-WmtFu15rErLMqW2_htnpUGE,8445
+tuffrl/board/static/index.html,sha256=1MuX9uobRR0xANWUR8P0PTFCDqW1GRZTE2qyboK6a_w,660
+tuffrl/board/static/assets/index-D4-8ALNT.js,sha256=huGu4wbmEPXiEcbjt6I0gFB4Lp5wCoeXottCr7RRvkk,70426
+tuffrl/board/static/assets/index-DWNZ33px.js,sha256=JM34GALSOxJsRQEOzW4ESacdi9999lMM4ckizi_1xsg,6053
+tuffrl/board/static/assets/index-fGqPXvQK.js,sha256=y2NbTw6zNb1f6p0UwIL_cGncElFl7kiRGeAwNv9u8k4,429137
+tuffrl/board/static/assets/index-xWSStQ1s.css,sha256=HCjwCOQ3kKBHst4Wu-G5h0zfpPCVqE3ari0Jsh7WvkQ,191068
+tuffrl/capture/__init__.py,sha256=rTITidcWEGnUPlzOu_1NKs8eJLk0ucIaK8nf-pwQQTs,204
+tuffrl/capture/stdout.py,sha256=zvHZWPSNcvMwjIQb3q3rZjnecpIbpzBMKXp1MH0Whco,2483
+tuffrl/capture/system.py,sha256=uzdGz5DrgMQnSJsxnZ2VqWlp660kYIMBpzMJxhUlUeA,3533
+tuffrl/events/__init__.py,sha256=KwvhWRB9LkjkMa37GH9MyQfynziFLNlaSoCDjFAbkSo,541
+tuffrl/events/crc32c.py,sha256=gUeQlY_TA8hG0jlxyeHm-4EqN4xTyQpMWD8nj1-VTHo,1440
+tuffrl/events/proto.py,sha256=wE5kUmyMKea2GCypWzhR7TKov-ISbcFL7lUkuzMjKmQ,3111
+tuffrl/events/reader.py,sha256=3HeO6rMrEYEki3V4J4Ur31m3CZwdM67UF23WZDpz9cw,2583
+tuffrl/events/records.py,sha256=ShrymEdeH4NprEk2_2fBXXVGaYrI3AlAcqZydQcoQLM,2621
+tuffrl/events/schema.py,sha256=ON3wwDBMRuXXHe_sKJfKJ4GITgFuCj7t7tWEgyUQgI0,13885
+tuffrl/events/writer.py,sha256=FuVoP5-weWvQtzWOieLu5GsZwqTNbXZFsyDrRCv5IpI,2681
+tuff_rl-0.1.0.dist-info/METADATA,sha256=3Yp_od4g6ppyVtYzAHt-BtfhvDik47uvCJHrBTtGsL8,7975
+tuff_rl-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+tuff_rl-0.1.0.dist-info/entry_points.txt,sha256=mYEdhA4cTP5XD49QwGbad0HLx_NTQ5vbzMv20q5OUi4,44
+tuff_rl-0.1.0.dist-info/top_level.txt,sha256=kMdtOCbwMYnhVHl8FsU4mROBiTsQLk3t7XqRIF9kCDU,7
+tuff_rl-0.1.0.dist-info/RECORD,,

tuff_rl-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

tuff_rl-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+tuff-rl = tuffrl.cli:main

tuff_rl-0.1.0.dist-info/licenses/LICENSE

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

tuff_rl-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+tuffrl

tuffrl/__init__.py

@@ -0,0 +1,53 @@
+"""tuff-rl: training logs as TensorBoard event files, with a live local board that starts itself.
+
+    import tuffrl
+    run = tuffrl.init(logdir="logs", name="sac-seed1", group="sac", config={"lr": 3e-4})
+    run.log({"train/loss": loss, "eval/return": ret}, step=step)
+    run.finish()
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+__version__ = "0.1.0"
+
+from .board import ensure_board  # noqa: E402 - needs __version__ above
+from .compat import SummaryWriter  # noqa: E402
+from .run import Run  # noqa: E402
+
+_current: Run | None = None
+
+
+def init(
+    logdir: str = "logs",
+    name: str | None = None,
+    group: str | None = None,
+    config: Mapping[str, Any] | None = None,
+    **options: Any,
+) -> Run:
+    """Starts a run under ``logdir`` and, unless ``board=False``, the board that shows it."""
+    global _current
+    _current = Run(logdir=logdir, name=name, group=group, config=config, **options)
+    return _current
+
+
+def log(metrics: Mapping[str, Any], step: int | None = None) -> None:
+    """Logs to the run started by :func:`init`."""
+    if _current is None:
+        raise RuntimeError("call tuffrl.init() first")
+    _current.log(metrics, step=step)
+
+
+def finish(status: str = "success") -> None:
+    if _current is not None:
+        _current.finish(status)
+
+
+def board(logdir: str = "logs", **options: Any) -> str | None:
+    """Opens (or finds) the board for a log directory, for runs written by any TensorBoard writer."""
+    return ensure_board(logdir, **options)
+
+
+__all__ = ["Run", "SummaryWriter", "__version__", "board", "finish", "init", "log"]

tuffrl/__main__.py

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

tuffrl/board/__init__.py

@@ -0,0 +1,5 @@
+"""The live board: a local web page that follows the event files in a log directory."""
+
+from .launch import ensure_board, stop_board
+
+__all__ = ["ensure_board", "stop_board"]

tuffrl/board/launch.py

@@ -0,0 +1,144 @@
+"""Starting the board from a training process, or finding the one already serving the log directory."""
+
+from __future__ import annotations
+
+import contextlib
+import getpass
+import json
+import os
+import socket
+import subprocess
+import sys
+import time
+import urllib.request
+import webbrowser
+from typing import Any
+
+from .lock import STATE_DIR, lock_path, read_lock
+
+DEFAULT_PORT = 6066
+START_TIMEOUT_SECS = 10.0
+
+
+def _healthy(info: dict[str, Any], logdir: str) -> bool:
+    url = info.get("url")
+    if not url:
+        return False
+    try:
+        with urllib.request.urlopen(f"{url}/api/health", timeout=1.5) as response:  # noqa: S310 - local URL from our own lock
+            health = json.load(response)
+    except (OSError, ValueError):
+        return False
+    return bool(health.get("ok")) and os.path.abspath(health.get("logdir", "")) == os.path.abspath(logdir)
+
+
+def is_remote_session() -> bool:
+    return any(os.environ.get(name) for name in ("SSH_CONNECTION", "SSH_CLIENT", "SSH_TTY"))
+
+
+def can_open_browser() -> bool:
+    override = os.environ.get("TUFFRL_OPEN_BROWSER")
+    if override is not None:
+        return override.strip().lower() not in ("0", "false", "no", "off", "")
+    if is_remote_session() or os.environ.get("CI"):
+        return False
+    if sys.platform.startswith("linux") and not (os.environ.get("DISPLAY") or os.environ.get("WAYLAND_DISPLAY")):
+        return False
+    return True
+
+
+def _spawn(logdir: str, host: str, port: int) -> None:
+    state_dir = os.path.join(os.path.abspath(logdir), STATE_DIR)
+    os.makedirs(state_dir, exist_ok=True)
+    log = open(os.path.join(state_dir, "board.log"), "ab")  # noqa: SIM115 - handed to the child
+    kwargs: dict[str, Any] = {"stdin": subprocess.DEVNULL, "stdout": log, "stderr": log, "close_fds": True}
+    if os.name == "nt":  # pragma: no cover
+        kwargs["creationflags"] = subprocess.DETACHED_PROCESS | subprocess.CREATE_NEW_PROCESS_GROUP
+    else:
+        kwargs["start_new_session"] = True  # the board outlives the training process
+    subprocess.Popen(
+        [sys.executable, "-m", "tuffrl", "board", os.path.abspath(logdir), "--host", host, "--port", str(port), "--no-browser"],
+        **kwargs,
+    )
+    log.close()
+
+
+def _claim_start(logdir: str) -> bool:
+    """Only one of several processes starting at once launches the board; the rest wait for it."""
+    path = f"{lock_path(logdir)}.starting"
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    try:
+        if time.time() - os.path.getmtime(path) > START_TIMEOUT_SECS * 2:
+            os.remove(path)  # left behind by a launch that died
+    except OSError:
+        pass
+    try:
+        os.close(os.open(path, os.O_CREAT | os.O_EXCL | os.O_WRONLY))
+        return True
+    except FileExistsError:
+        return False
+
+
+def _release_start(logdir: str) -> None:
+    with contextlib.suppress(OSError):
+        os.remove(f"{lock_path(logdir)}.starting")
+
+
+def ensure_board(
+    logdir: str,
+    *,
+    host: str = "127.0.0.1",
+    port: int | None = None,
+    open_browser: bool | None = None,
+    announce: bool = True,
+) -> str | None:
+    """Returns the URL of the board serving ``logdir``, starting one when none is running."""
+    port = port or int(os.environ.get("TUFFRL_BOARD_PORT", DEFAULT_PORT))
+    host = os.environ.get("TUFFRL_BOARD_HOST", host)
+    info = read_lock(logdir)
+    started = False
+    if not (info and _healthy(info, logdir)):
+        claimed = _claim_start(logdir)
+        try:
+            if claimed:
+                _spawn(logdir, host, port)
+                started = True
+            deadline = time.time() + START_TIMEOUT_SECS
+            info = None
+            while time.time() < deadline:
+                candidate = read_lock(logdir)
+                if candidate and _healthy(candidate, logdir):
+                    info = candidate
+                    break
+                time.sleep(0.2)
+        finally:
+            if claimed:
+                _release_start(logdir)
+    if not info:
+        if announce:
+            print(f"[tuffrl] the board did not start; see {os.path.join(logdir, STATE_DIR, 'board.log')}", file=sys.stderr)
+        return None
+    url = str(info["url"])
+    if announce:
+        print(f"[tuffrl] board: {url}  (logdir {os.path.abspath(logdir)})", file=sys.stderr, flush=True)
+        if is_remote_session():
+            board_port = info.get("port")
+            print(
+                f"[tuffrl] from your own machine: ssh -N -L {board_port}:127.0.0.1:{board_port} "
+                f"{getpass.getuser()}@{socket.gethostname()}  then open http://127.0.0.1:{board_port}",
+                file=sys.stderr, flush=True,
+            )
+    if started and (can_open_browser() if open_browser is None else open_browser):
+        webbrowser.open(url)
+    return url
+
+
+def stop_board(logdir: str) -> bool:
+    info = read_lock(logdir)
+    if not info or not info.get("pid"):
+        return False
+    try:
+        os.kill(int(info["pid"]), 15)
+    except OSError:
+        return False
+    return True

tuffrl/board/lock.py

@@ -0,0 +1,40 @@
+"""The file in a log directory that says which board is serving it."""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import os
+from typing import Any
+
+STATE_DIR = ".tuffrl"
+LOCK_NAME = "board.json"
+
+
+def lock_path(logdir: str) -> str:
+    return os.path.join(os.path.abspath(logdir), STATE_DIR, LOCK_NAME)
+
+
+def read_lock(logdir: str) -> dict[str, Any] | None:
+    try:
+        with open(lock_path(logdir), encoding="utf-8") as handle:
+            data = json.load(handle)
+    except (OSError, ValueError):
+        return None
+    return data if isinstance(data, dict) else None
+
+
+def write_lock(logdir: str, data: dict[str, Any]) -> None:
+    path = lock_path(logdir)
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    temporary = f"{path}.{os.getpid()}.tmp"
+    with open(temporary, "w", encoding="utf-8") as handle:
+        json.dump(data, handle)
+    os.replace(temporary, path)  # readers see the old file or the new one, never half of one
+
+
+def clear_lock(logdir: str, pid: int) -> None:
+    data = read_lock(logdir)
+    if data and data.get("pid") == pid:
+        with contextlib.suppress(OSError):
+            os.remove(lock_path(logdir))