Metadata-Version: 2.3
Name: pbs-tui
Version: 0.5.2
Summary: Textual TUI dashboard for monitoring PBS Pro schedulers
Author: Sam Foreman, Argonne Leadership Computing Facility
Author-email: Sam Foreman <foremans@anl.gov>
Requires-Dist: textual
Requires-Dist: pytest>=8.4.2 ; extra == 'dev'
Requires-Python: >=3.10
Provides-Extra: dev
Description-Content-Type: text/markdown

# PBS Pro Textual TUI

A terminal user interface built with [Textual](https://textual.textualize.io/) for monitoring
[PBS Pro](https://altair.com/pbs-professional) schedulers at the
[Argonne Leadership Computing Facility](https://alcf.anl.gov). 

The dashboard surfaces job,
queue, and node activity in a single view and refreshes itself automatically so operators can
track workload health in real time.

<table>
<tr>
<th>Racks Grid (Polaris)</th>
<th>Cluster Grid (Polaris)</th>
</tr>
<tr>
<td><img src="assets/racks-polaris.png" alt="Rack grid showing per-node utilization across the Polaris layout" /></td>
<td><img src="assets/cluster-polaris.png" alt="Cluster grid showing proportional node utilization on Polaris" /></td>
</tr>
<tr>
<th>Racks Grid (Aurora)</th>
<th>Cluster Grid (Aurora)</th>
</tr>
<tr>
<td><img src="assets/racks-aurora.png" alt="Rack grid showing per-node utilization across the Aurora layout" /></td>
<td><img src="assets/cluster-aurora.png" alt="Cluster grid showing proportional node utilization on Aurora" /></td>
</tr>
</table>

<details><summary>More views &amp; themes</summary>

<table>
<tr>
<th>Cluster Grid (dark)</th>
<th>Jobs Table (dark)</th>
</tr>
<tr>
<td><img src="assets/cluster-dark.png" alt="Cluster grid (dark)" /></td>
<td><img src="assets/jobs-dark.png" alt="Jobs table (dark)" /></td>
</tr>
<tr>
<th>Cluster Grid (light)</th>
<th>Jobs Table (light)</th>
</tr>
<tr>
<td><img src="assets/cluster-light.png" alt="Cluster grid (light)" /></td>
<td><img src="assets/jobs-light.png" alt="Jobs table (light)" /></td>
</tr>
<tr>
<th>Cluster Grid (Catppuccin)</th>
<th>Cluster Grid (One Dark)</th>
</tr>
<tr>
<td><img src="assets/cluster-catppuccin.png" alt="Cluster grid (catppuccin)" /></td>
<td><img src="assets/cluster-onedark.png" alt="Cluster grid (onedark)" /></td>
</tr>
</table>

</details>


- Try it out!

  ```bash
  # if you still haven't installed uv:
  # curl -LsSf https://astral.sh/uv/install.sh | sh
  uvx pbs-tui
  ```

## Features

- **Cluster grid** – visual map of cluster node utilization with proportional legend bar.
  Click a job block to see its details. Colors adapt to the active theme.
- **Rack grid** – per-rack node-level view modeled on the ALCF status page.
  Click a node to highlight every node a job occupies; click a rack name to filter the
  job sidebar. Detects Aurora and Polaris cabinet hostnames; falls back to a generic layout for
  other clusters.
- **Live PBS data** – prefers the JSON (`-F json`) output of `qstat`/`pbsnodes` and falls back to
  XML or text parsing so schedulers without newer flags continue to work.
- **Automatic refresh** – updates every 30 seconds by default with a manual refresh binding
  (`r`).
- **Rich tables** – sortable (via cursor) tables for jobs, nodes, and queues with detail views
  for the selected record.
- **Themes** – ships with `pbs-dark`, `pbs-light`, `ansi-dark`, and `ansi-light` themes.
  The `ansi-*` variants use muted 256-color palette tones that blend with your terminal
  colorscheme. Switch via the command palette (`Ctrl+P`).
- **Fallback sample data** – bundled realistic mock cluster (~560 nodes, ~40 jobs) for demoing
  without a production scheduler (`PBS_TUI_SAMPLE_DATA=1`).
- **Inline snapshot** – render the current queue as a Rich table with `pbs-tui --inline` and
  optionally write a Markdown summary alongside it.

## Installation

```bash
uv pip install pbs-tui
```

<!--
1. Ensure Python 3.10 or newer is available.
2. Install the project (and Textual) in your environment:

   ```bash
   pip install -e .
   ```

   Development extras (formatting, etc.) can be installed with `pip install -e .[dev]`.
-->

## Usage

Launch the dashboard once the PBS CLI utilities (`qstat`, `pbsnodes`) are on the `PATH`:

```bash
pbs-tui
```

The same entry point is available via `python -m pbs_tui`. The interface displays a summary
panel, tables for jobs/nodes/queues, and a detail pane for the selected row. Refreshing happens
automatically; press `r` to force an immediate update.

Adjust the refresh cadence with `pbs-tui --refresh-interval 60` (seconds) if you prefer a slower or
faster polling loop.

### Key bindings

| Key |       Action           |
|:---:|:---------------------- |
| `q` | Quit the application   |
| `r` | Refresh immediately    |
| `g` | Focus the cluster grid |
| `k` | Focus the rack grid    |
| `j` | Focus the jobs table   |
| `n` | Focus the nodes table  |
| `u` | Focus the queues table |
| `d` | Toggle detail panel    |

Use tab and the arrow keys/`PageUp`/`PageDown` to move through rows once a table has focus.

### Sample mode

If you want to explore the UI without a live PBS cluster, export `PBS_TUI_SAMPLE_DATA=1`
(or pass `force_sample=True` to `PBSDataFetcher`). The application will display bundled example
jobs, nodes, and queues along with a warning banner indicating that the data is synthetic.

### Headless / automated runs

For automated testing or CI environments without an interactive terminal you can run the TUI in
headless mode by exporting `PBS_TUI_HEADLESS=1`. Pairing this with `PBS_TUI_AUTOPILOT=quit`
presses the `q` binding automatically after startup so `pbs-tui` exits cleanly once the interface
has rendered its first update.

### Inline snapshot mode

When running non-interactively you can emit a Rich-rendered table summarising the active PBS jobs
instead of starting the Textual interface:

```bash
PBS_TUI_SAMPLE_DATA=1 pbs-tui --inline
```

The command prints a table that can be pasted into terminals that support Unicode box drawing. Pass
`--file snapshot.md` alongside `--inline` to also write an aligned Markdown table to `snapshot.md`
for sharing in chat or documentation systems. Any warnings raised while collecting data are written
to standard error so they remain visible in logs.

## Architecture

- `pbs_tui.fetcher.PBSDataFetcher` orchestrates `qstat`/`pbsnodes` calls, preferring JSON output and
  falling back to XML/text before converting everything into structured dataclasses (`Job`, `Node`,
  `Queue`).
- `pbs_tui.app.PBSTUI` is the Textual application that renders the dashboard, periodically asks
  the fetcher for new data, and updates the widgets.
- `pbs_tui.samples.sample_snapshot` provides the demonstration snapshot used when PBS commands
  cannot be executed.

The UI styles are defined in `pbs_tui/app.tcss`. Adjust the CSS to change layout or theme
attributes.

## Development notes

- The application refresh interval defaults to 30 seconds. Pass a different value to
  `PBSTUI(refresh_interval=...)` if desired.
- Errors encountered while running PBS commands are surfaced in the status bar so operators can
  quickly see when data is stale.
- When both PBS utilities are unavailable and the fallback is disabled, the UI will show an empty
  dashboard with an error message in the status bar.

