Metadata-Version: 2.4
Name: constella-gpu-tui
Version: 0.1.2
Summary: Constella backend with a keyboard-first Textual terminal interface.
Project-URL: Homepage, https://github.com/kuma-loong/Constella
Project-URL: Repository, https://github.com/kuma-loong/Constella
Project-URL: Documentation, https://github.com/kuma-loong/Constella/blob/main/packages/tui/README.md
Project-URL: Issues, https://github.com/kuma-loong/Constella/issues
License-Expression: MIT
License-File: LICENSE
Keywords: ascend,gpu,monitoring,nvidia,textual,tui
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: License :: OSI Approved :: MIT License
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 :: System :: Monitoring
Requires-Python: >=3.10
Requires-Dist: constella-gpu-backend==0.1.2
Requires-Dist: textual<9,>=8.0.0
Requires-Dist: websockets>=13.0
Description-Content-Type: text/markdown

# Constella TUI

`constella-gpu-tui` installs the Constella backend together with its
keyboard-first Textual terminal client. It reads the realtime `/ws/cluster`
stream and historical analytics APIs, so live monitoring and completed
workloads stay available in one terminal workspace.

Constella natively supports heterogeneous accelerator clusters. Version 0.1.2
supports NVIDIA GPUs and Ascend NPUs.

## Views

- **Overview** — compact node/GPU navigation, selected-GPU processes, telemetry, and a live Braille dot curve.
- **Cluster** — complete node inventory and the selected node's hardware details.
- **Rankings** — user GPU-hours, jobs, and anomaly rankings from persisted analytics.
- **History** — utilization and memory dot curves plus a GPU-by-time utilization heatmap.

Rankings and History require the manager database. They show an explicit unavailable state when the manager was started with `--no-db`.

## Run

Install the TUI-focused distribution:

```bash
pip install constella-gpu-tui
```

Start a backend locally, then open the TUI:

```bash
constella service start
constella tui
# or
constella-tui
```

Connect to a remote manager through an SSH tunnel or a directly reachable endpoint:

```bash
constella tui --url http://127.0.0.1:8765
constella-tui --url https://gpu.example.com
```

`CONSTELLA_URL` can provide the default manager URL.

## Keyboard

| Key | Action |
| --- | --- |
| `1` … `4` | Open Overview, Cluster, Rankings, or History |
| `Tab`, `Shift+Tab` | Move focus |
| Arrow keys, `j`, `k` | Move through nodes and table rows |
| `n`, `g` | Select the next node or GPU |
| `[`, `]` | Select the previous or next analytics time range |
| `r` | Reconnect immediately |
| `?` | Open keyboard help |
| `q` | Quit |

The selected node and GPU survive realtime refreshes and remain shared across views. The client reconnects automatically after a dropped connection. No agent token is needed because these read-only endpoints follow the same access boundary as the Web UI.

Use `constella-gpu` when both Web and TUI frontends are wanted, or
`constella-gpu-backend` for an API-only installation.
