Metadata-Version: 2.4
Name: lightning-metrics-tui
Version: 0.2.0
Summary: TensorBoard-like terminal monitor for PyTorch Lightning metrics, CSVLogger runs, and live run comparison.
Project-URL: Repository, https://github.com/erik-ayari/ltui
Project-URL: Issues, https://github.com/erik-ayari/ltui/issues
Project-URL: Documentation, https://github.com/erik-ayari/ltui#readme
Project-URL: Changelog, https://github.com/erik-ayari/ltui/blob/main/CHANGELOG.md
Project-URL: Examples, https://github.com/erik-ayari/ltui/tree/main/examples
Author: Erik Ayari
License-Expression: MIT
License-File: LICENSE
Keywords: csvlogger,deep-learning,experiment-tracking,lightning,machine-learning,metrics,plotext,pytorch-lightning,ssh,tensorboard,terminal,textual,tmux,training-monitor,tui,visualization
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Visualization
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.11
Requires-Dist: pandas>=2.2
Requires-Dist: plotext>=5.3
Requires-Dist: rapidfuzz>=3.0
Requires-Dist: textual>=0.80
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: twine>=6.0; extra == 'dev'
Provides-Extra: logger
Requires-Dist: lightning>=2.0; extra == 'logger'
Requires-Dist: pillow>=10.0; extra == 'logger'
Description-Content-Type: text/markdown

# ltui - terminal TensorBoard for PyTorch Lightning metrics

[![PyPI](https://img.shields.io/pypi/v/lightning-metrics-tui.svg)](https://pypi.org/project/lightning-metrics-tui/)

Monitor PyTorch Lightning training runs directly over SSH or inside tmux.
No browser, no TensorBoard server, no port forwarding.

```bash
pipx install lightning-metrics-tui
ltui --demo
```

For your own Lightning logs:

```bash
ltui ./lightning_logs
```

<p>
  <a href="https://github.com/erik-ayari/ltui/blob/main/docs/screenshots/multiplot.png">
    <img src="https://raw.githubusercontent.com/erik-ayari/ltui/main/docs/screenshots/multiplot.png" alt="Grouped multiplot view in ltui" width="100%">
  </a>
</p>
<p>
  <a href="https://github.com/erik-ayari/ltui/blob/main/docs/screenshots/loss-log-scale-comparison.png">
    <img src="https://raw.githubusercontent.com/erik-ayari/ltui/main/docs/screenshots/loss-log-scale-comparison.png" alt="Run comparison plot in ltui" width="100%">
  </a>
</p>

## Why ltui?

`ltui` is a TensorBoard-like terminal monitor for PyTorch Lightning metrics. It is built for remote training sessions where opening a browser, starting a TensorBoard server, or forwarding ports is friction.

Use it to inspect Lightning `CSVLogger` runs, compare versions, group train/validation metrics, smooth noisy curves, inspect run configs, and navigate everything from the terminal.

## Quick start

```bash
pipx install lightning-metrics-tui
ltui --demo
```

For one-shot use without a persistent install:

```bash
pipx run --spec lightning-metrics-tui ltui --demo
```

The command remains `ltui`. The install package is `lightning-metrics-tui`, and the Python module remains `ltui`.

## Try the demo

```bash
ltui --demo
```

The demo opens bundled Lightning-style `CSVLogger` logs with three versions, training and validation loss, accuracy, learning rate, and `hparams.yaml` files. The demo data is copied to a temporary directory before launch.

From a source checkout, the same example data is available at:

```bash
ltui examples/lightning_logs
```

## Usage with existing Lightning logs

Point `ltui` at any directory containing Lightning logs:

```bash
ltui /path/to/log/root
```

Common examples:

```bash
ltui ./outputs
ltui ./lightning_logs
ltui /data/experiments/stage1
```

On startup, `ltui` recursively discovers supported run directories, selects the latest modified run by default, and chooses a loss metric when one is available. The preferred x-axis is `step`, then `epoch`, then row index. Press `a` to toggle between step and epoch mode.

## Usage with PyTorch Lightning CSVLogger

Existing Lightning `CSVLogger` runs work without changing your training code. Every discovered `metrics.csv` is treated as one selectable run/version.

Supported layouts include:

```text
lightning_logs/version_0/metrics.csv
run_a/version_0/metrics.csv
run_a/lightning_logs/version_0/metrics.csv
experiments/group_1/run_a/lightning_logs/version_3/metrics.csv
```

For native `metrics.csv` files, train/validation grouping uses the standard prefixes:

```text
train_
val_
```

Examples:

```text
train_loss + val_loss -> loss
train_recon_loss + val_recon_loss -> recon_loss
train_kl + val_kl -> kl
```

Lightning step/epoch suffixes are handled as part of the same family, so `train_loss_step`, `train_loss_epoch`, and `val_loss` appear as `loss`.

## Usage with LtuiLogger

`LtuiLogger` is an optional PyTorch Lightning logger for new runs. It writes a small manifest, one narrow CSV file per metric series, optional image folders, and hyperparameters as JSON.

Install the optional logger dependencies in your training environment:

```bash
python -m pip install "lightning-metrics-tui[logger]"
```

Use it with Lightning:

```python
from lightning.pytorch import Trainer
from ltui.lightning import LtuiLogger

logger = LtuiLogger(
    save_dir="outputs",
    name="stage1",
)

trainer = Trainer(logger=logger)
```

Path-style metric names create a hierarchy in the metric selector and multiplot view:

```python
self.log("train/loss/kl", train_kl)
self.log("val/loss/kl", val_kl)
self.log("train/loss/recon", train_recon)
self.log("val/loss/recon", val_recon)
```

The logger also accepts `train_` and `val_` style names with the default prefixes, so simple metric names like `train_loss` and `val_loss` remain grouped as `loss`.

Images can be logged with the same path-style hierarchy:

```python
logger.log_image("train/recon/sample", image, step=global_step, epoch=current_epoch)
logger.experiment.add_image("val/recon/sample", image_tensor, global_step=global_step)
```

Press `i` in the TUI to choose an image stream. Image viewing launches `feh` when it is installed.

## Features

- Live terminal monitoring for PyTorch Lightning runs
- Lightning `CSVLogger` `metrics.csv` compatibility
- Optional `LtuiLogger` for structured metric and image logs
- Train/validation metric grouping
- Grouped multiplot pages for sibling metrics
- Multi-run comparison with color-coded legends
- Step and epoch x-axis modes with Lightning-friendly validation alignment
- Log scaling and EMA smoothing
- YAML config inspection for runs with a unique config file
- Keyboard-first selectors with fuzzy search

## Why use ltui instead of TensorBoard?

Use `ltui` when you:

- train on a remote machine over SSH
- work inside tmux
- do not want to forward ports
- want to inspect `CSVLogger`-compatible metrics quickly
- want terminal-native run comparison
- want a lightweight monitor without starting a TensorBoard server

TensorBoard is still the broader tool for full experiment dashboards, plugin views, embeddings, and richer browser-based inspection. `ltui` focuses on fast scalar metric monitoring in the terminal.

## How is this different from generic terminal plotters?

Generic terminal plotters can display scalar data, TensorBoard logs, or CSV files. `ltui` is focused on PyTorch Lightning training workflows: Lightning-style log directories, `CSVLogger`-compatible metrics, train/validation metric grouping, run comparison, smoothing, config inspection, and terminal-native navigation.

## Installation

Recommended CLI install:

```bash
pipx install lightning-metrics-tui
```

Normal pip install:

```bash
python -m pip install lightning-metrics-tui
```

Optional logger dependencies:

```bash
python -m pip install "lightning-metrics-tui[logger]"
```

The TUI itself does not require PyTorch Lightning.

## Controls

| Key | Action |
| --- | --- |
| `r` | Open run/version selector |
| `c` | Open config viewer for runs with a unique YAML config |
| `m` | Open metric selector |
| `i` | Open image selector and launch `feh` for the selected image stream |
| `/` | Fuzzy search inside selector |
| `arrow keys` | Navigate selector or selected plot in multiplot mode; left/right jump between models in run/config selectors |
| `space` | Toggle selection in selector, open multiplot on main screen |
| `enter` | Apply selector, focus selected plot in multiplot mode |
| `escape` | Clear plot selection in multiplot mode |
| `n` | Next selected metric/family, or next page in multiplot mode |
| `p` | Previous selected metric/family, or previous page in multiplot mode |
| `a` | Toggle x-axis between step and epoch |
| `d` | Toggle dark/light plot theme |
| `s` | Toggle smoothing |
| `x` | Toggle log-x |
| `y` | Toggle log-y |
| `q` | Quit |

## Development

```bash
python -m pip install -e ".[dev]"
pytest
python -m build
```

## Changelog / release notes

See [CHANGELOG.md](CHANGELOG.md).
