nptop 0.1.0__tar.gz

nptop-0.1.0/LICENSE

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

nptop-0.1.0/PKG-INFO

@@ -0,0 +1,118 @@
+Metadata-Version: 2.4
+Name: nptop
+Version: 0.1.0
+Summary: An nvitop-like interactive monitor for Ascend NPUs
+Author: ZYM-PKU
+License-Expression: MIT
+Keywords: npu,ascend,monitor,npu-smi,tui
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# nptop
+
+`nptop` 是一个面向华为昇腾 NPU 的轻量级、零 Python 依赖监控工具，提供类似
+`nvitop` 的实时设备和进程视图。它调用机器已有的 `npu-smi`，不要求安装 CANN
+Python SDK。
+
+![Python](https://img.shields.io/badge/python-3.9%2B-blue)
+![License](https://img.shields.io/badge/license-MIT-green)
+
+## 功能
+
+- 每张 NPU 独占一行，AICore 利用率与 HBM 占用率均使用彩色进度条
+- 展示 NPU 进程、用户、宿主机 CPU/内存、NPU 显存和完整命令行
+- 固定高度可滚动视图，启动时位于顶部，支持键盘和鼠标滚轮
+- 交互式刷新和按显存、CPU、PID 排序
+- 支持单次文本输出和 JSON 输出，方便脚本、巡检与监控系统集成
+- 无第三方运行时依赖；兼容容器里的宿主 PID 信息缺失场景
+- 对不同 `npu-smi` 版本采用表头和字段语义解析，不依赖固定表格宽度
+
+## 安装
+
+机器需要已安装并可运行 `npu-smi`。
+
+```bash
+pip install nptop
+nptop
+```
+
+从 Git 仓库安装：
+
+```bash
+pip install git+https://github.com/ZYM-PKU/nptop.git
+```
+
+开发安装：
+
+```bash
+git clone https://github.com/ZYM-PKU/nptop.git
+cd nptop
+python -m pip install -e .
+nptop
+```
+
+## 使用
+
+```bash
+nptop                     # 交互视图，每 2 秒刷新
+nptop -i 1                # 每秒刷新（-i 是 interval 的短参数）
+nptop -d 0,2,3            # 只看指定 NPU
+nptop -1                  # 输出一次后退出
+nptop --json              # JSON 快照
+nptop --sort cpu          # 进程按 CPU 排序
+nptop --raw               # 输出原始 npu-smi，便于兼容性排查
+```
+
+交互模式按键：方向键或 `j`/`k` 逐行滚动，`PageUp`/`PageDown` 翻页，
+`Home`/`g` 返回顶部，`End`/`G` 到达底部，也支持鼠标滚轮。`q` 退出，`r`
+立即刷新，`m` 按 NPU 显存排序，`c` 按 CPU 排序，`p` 按 PID 排序。也可以使用
+`Ctrl-C` 退出。
+
+完整参数见：
+
+```bash
+nptop --help
+```
+
+如果 `npu-smi` 不在 `PATH`，可以显式指定：
+
+```bash
+NPUTOP_NPU_SMI=/usr/local/Ascend/driver/tools/npu-smi nptop
+```
+
+## 容器说明
+
+容器需要能够执行 `npu-smi`，并挂载相应的昇腾设备和驱动目录。`npu-smi`
+返回的宿主机 PID 在容器 PID 命名空间内可能不可见；这时 USER、CPU、宿主机内存
+和完整命令会显示为 `?`/`-`，NPU 指标不受影响。
+
+## 开发与发布
+
+```bash
+python -m pip install pytest build twine
+pytest
+python -m build
+twine check dist/*
+twine upload dist/*
+```
+
+发布前请把 `pyproject.toml` 中的 `project.urls` 替换成实际 Git 仓库地址。版本号在
+`pyproject.toml` 与 `src/nputop/__init__.py` 中维护。
+
+## 已知范围
+
+当前后端针对华为昇腾 `npu-smi info`。不同驱动大版本如果改变了表格语义，可用
+`nptop --raw` 保存输出并提交 issue。项目结构允许后续增加其他 NPU 厂商后端。
+
+## License
+
+MIT

nptop-0.1.0/README.md

@@ -0,0 +1,99 @@
+# nptop
+
+`nptop` 是一个面向华为昇腾 NPU 的轻量级、零 Python 依赖监控工具，提供类似
+`nvitop` 的实时设备和进程视图。它调用机器已有的 `npu-smi`，不要求安装 CANN
+Python SDK。
+
+![Python](https://img.shields.io/badge/python-3.9%2B-blue)
+![License](https://img.shields.io/badge/license-MIT-green)
+
+## 功能
+
+- 每张 NPU 独占一行，AICore 利用率与 HBM 占用率均使用彩色进度条
+- 展示 NPU 进程、用户、宿主机 CPU/内存、NPU 显存和完整命令行
+- 固定高度可滚动视图，启动时位于顶部，支持键盘和鼠标滚轮
+- 交互式刷新和按显存、CPU、PID 排序
+- 支持单次文本输出和 JSON 输出，方便脚本、巡检与监控系统集成
+- 无第三方运行时依赖；兼容容器里的宿主 PID 信息缺失场景
+- 对不同 `npu-smi` 版本采用表头和字段语义解析，不依赖固定表格宽度
+
+## 安装
+
+机器需要已安装并可运行 `npu-smi`。
+
+```bash
+pip install nptop
+nptop
+```
+
+从 Git 仓库安装：
+
+```bash
+pip install git+https://github.com/ZYM-PKU/nptop.git
+```
+
+开发安装：
+
+```bash
+git clone https://github.com/ZYM-PKU/nptop.git
+cd nptop
+python -m pip install -e .
+nptop
+```
+
+## 使用
+
+```bash
+nptop                     # 交互视图，每 2 秒刷新
+nptop -i 1                # 每秒刷新（-i 是 interval 的短参数）
+nptop -d 0,2,3            # 只看指定 NPU
+nptop -1                  # 输出一次后退出
+nptop --json              # JSON 快照
+nptop --sort cpu          # 进程按 CPU 排序
+nptop --raw               # 输出原始 npu-smi，便于兼容性排查
+```
+
+交互模式按键：方向键或 `j`/`k` 逐行滚动，`PageUp`/`PageDown` 翻页，
+`Home`/`g` 返回顶部，`End`/`G` 到达底部，也支持鼠标滚轮。`q` 退出，`r`
+立即刷新，`m` 按 NPU 显存排序，`c` 按 CPU 排序，`p` 按 PID 排序。也可以使用
+`Ctrl-C` 退出。
+
+完整参数见：
+
+```bash
+nptop --help
+```
+
+如果 `npu-smi` 不在 `PATH`，可以显式指定：
+
+```bash
+NPUTOP_NPU_SMI=/usr/local/Ascend/driver/tools/npu-smi nptop
+```
+
+## 容器说明
+
+容器需要能够执行 `npu-smi`，并挂载相应的昇腾设备和驱动目录。`npu-smi`
+返回的宿主机 PID 在容器 PID 命名空间内可能不可见；这时 USER、CPU、宿主机内存
+和完整命令会显示为 `?`/`-`，NPU 指标不受影响。
+
+## 开发与发布
+
+```bash
+python -m pip install pytest build twine
+pytest
+python -m build
+twine check dist/*
+twine upload dist/*
+```
+
+发布前请把 `pyproject.toml` 中的 `project.urls` 替换成实际 Git 仓库地址。版本号在
+`pyproject.toml` 与 `src/nputop/__init__.py` 中维护。
+
+## 已知范围
+
+当前后端针对华为昇腾 `npu-smi info`。不同驱动大版本如果改变了表格语义，可用
+`nptop --raw` 保存输出并提交 issue。项目结构允许后续增加其他 NPU 厂商后端。
+
+## License
+
+MIT

nptop-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "nptop"
+version = "0.1.0"
+description = "An nvitop-like interactive monitor for Ascend NPUs"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+authors = [{ name = "ZYM-PKU" }]
+keywords = ["npu", "ascend", "monitor", "npu-smi", "tui"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Operating System :: POSIX :: Linux",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Topic :: System :: Monitoring",
+]
+dependencies = []
+
+[project.scripts]
+nptop = "nputop.cli:main"
+nputop = "nputop.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+addopts = "-q"
+testpaths = ["tests"]

nptop-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

nptop-0.1.0/src/nptop.egg-info/PKG-INFO

@@ -0,0 +1,118 @@
+Metadata-Version: 2.4
+Name: nptop
+Version: 0.1.0
+Summary: An nvitop-like interactive monitor for Ascend NPUs
+Author: ZYM-PKU
+License-Expression: MIT
+Keywords: npu,ascend,monitor,npu-smi,tui
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# nptop
+
+`nptop` 是一个面向华为昇腾 NPU 的轻量级、零 Python 依赖监控工具，提供类似
+`nvitop` 的实时设备和进程视图。它调用机器已有的 `npu-smi`，不要求安装 CANN
+Python SDK。
+
+![Python](https://img.shields.io/badge/python-3.9%2B-blue)
+![License](https://img.shields.io/badge/license-MIT-green)
+
+## 功能
+
+- 每张 NPU 独占一行，AICore 利用率与 HBM 占用率均使用彩色进度条
+- 展示 NPU 进程、用户、宿主机 CPU/内存、NPU 显存和完整命令行
+- 固定高度可滚动视图，启动时位于顶部，支持键盘和鼠标滚轮
+- 交互式刷新和按显存、CPU、PID 排序
+- 支持单次文本输出和 JSON 输出，方便脚本、巡检与监控系统集成
+- 无第三方运行时依赖；兼容容器里的宿主 PID 信息缺失场景
+- 对不同 `npu-smi` 版本采用表头和字段语义解析，不依赖固定表格宽度
+
+## 安装
+
+机器需要已安装并可运行 `npu-smi`。
+
+```bash
+pip install nptop
+nptop
+```
+
+从 Git 仓库安装：
+
+```bash
+pip install git+https://github.com/ZYM-PKU/nptop.git
+```
+
+开发安装：
+
+```bash
+git clone https://github.com/ZYM-PKU/nptop.git
+cd nptop
+python -m pip install -e .
+nptop
+```
+
+## 使用
+
+```bash
+nptop                     # 交互视图，每 2 秒刷新
+nptop -i 1                # 每秒刷新（-i 是 interval 的短参数）
+nptop -d 0,2,3            # 只看指定 NPU
+nptop -1                  # 输出一次后退出
+nptop --json              # JSON 快照
+nptop --sort cpu          # 进程按 CPU 排序
+nptop --raw               # 输出原始 npu-smi，便于兼容性排查
+```
+
+交互模式按键：方向键或 `j`/`k` 逐行滚动，`PageUp`/`PageDown` 翻页，
+`Home`/`g` 返回顶部，`End`/`G` 到达底部，也支持鼠标滚轮。`q` 退出，`r`
+立即刷新，`m` 按 NPU 显存排序，`c` 按 CPU 排序，`p` 按 PID 排序。也可以使用
+`Ctrl-C` 退出。
+
+完整参数见：
+
+```bash
+nptop --help
+```
+
+如果 `npu-smi` 不在 `PATH`，可以显式指定：
+
+```bash
+NPUTOP_NPU_SMI=/usr/local/Ascend/driver/tools/npu-smi nptop
+```
+
+## 容器说明
+
+容器需要能够执行 `npu-smi`，并挂载相应的昇腾设备和驱动目录。`npu-smi`
+返回的宿主机 PID 在容器 PID 命名空间内可能不可见；这时 USER、CPU、宿主机内存
+和完整命令会显示为 `?`/`-`，NPU 指标不受影响。
+
+## 开发与发布
+
+```bash
+python -m pip install pytest build twine
+pytest
+python -m build
+twine check dist/*
+twine upload dist/*
+```
+
+发布前请把 `pyproject.toml` 中的 `project.urls` 替换成实际 Git 仓库地址。版本号在
+`pyproject.toml` 与 `src/nputop/__init__.py` 中维护。
+
+## 已知范围
+
+当前后端针对华为昇腾 `npu-smi info`。不同驱动大版本如果改变了表格语义，可用
+`nptop --raw` 保存输出并提交 issue。项目结构允许后续增加其他 NPU 厂商后端。
+
+## License
+
+MIT

nptop-0.1.0/src/nptop.egg-info/SOURCES.txt

@@ -0,0 +1,17 @@
+LICENSE
+README.md
+pyproject.toml
+src/nptop.egg-info/PKG-INFO
+src/nptop.egg-info/SOURCES.txt
+src/nptop.egg-info/dependency_links.txt
+src/nptop.egg-info/entry_points.txt
+src/nptop.egg-info/top_level.txt
+src/nputop/__init__.py
+src/nputop/__main__.py
+src/nputop/backend.py
+src/nputop/cli.py
+src/nputop/models.py
+src/nputop/render.py
+tests/test_backend.py
+tests/test_cli.py
+tests/test_render.py

nptop-0.1.0/src/nptop.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

nptop-0.1.0/src/nptop.egg-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+nptop = nputop.cli:main
+nputop = nputop.cli:main

nptop-0.1.0/src/nptop.egg-info/top_level.txt

@@ -0,0 +1 @@
+nputop

nptop-0.1.0/src/nputop/__init__.py

@@ -0,0 +1,6 @@
+"""nptop: an interactive Ascend NPU process monitor."""
+
+from .models import DeviceInfo, ProcessInfo, Snapshot
+
+__all__ = ["DeviceInfo", "ProcessInfo", "Snapshot"]
+__version__ = "0.1.0"

nptop-0.1.0/src/nputop/__main__.py

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

nptop-0.1.0/src/nputop/backend.py

@@ -0,0 +1,219 @@
+from __future__ import annotations
+
+import os
+import re
+import shutil
+import subprocess
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Iterable, List, Optional, Sequence, Tuple
+
+from .models import DeviceInfo, ProcessInfo, Snapshot
+
+
+class BackendError(RuntimeError):
+    """The NPU metrics backend could not produce a snapshot."""
+
+
+def _number(value: str, kind=float):
+    match = re.search(r"-?\d+(?:\.\d+)?", value)
+    return kind(float(match.group())) if match else None
+
+
+def _memory_pairs(value: str) -> List[Tuple[int, int]]:
+    return [
+        (int(used), int(total))
+        for used, total in re.findall(r"(\d+)\s*/\s*(\d+)", value)
+    ]
+
+
+def _cells(line: str) -> List[str]:
+    if not line.lstrip().startswith("|"):
+        return []
+    return [cell.strip() for cell in line.strip().strip("|").split("|")]
+
+
+def parse_npu_smi(output: str) -> Snapshot:
+    """Parse the stable tabular surface of ``npu-smi info``.
+
+    Ascend releases have changed column widths and added columns over time.  This
+    parser therefore keys off table headers and slash-separated memory values,
+    rather than relying on exact character offsets.
+    """
+    version_match = re.search(r"npu-smi\s+([^\s|]+)", output, re.IGNORECASE)
+    snapshot = Snapshot(
+        driver_version=version_match.group(1) if version_match else "unknown",
+        timestamp=datetime.now(timezone.utc),
+    )
+    lines = output.splitlines()
+    device_header = next(
+        (i for i, line in enumerate(lines) if "NPU" in line and "Health" in line),
+        None,
+    )
+    process_header = next(
+        (
+            i
+            for i, line in enumerate(lines)
+            if "Process id" in line and "Process memory" in line
+        ),
+        None,
+    )
+
+    if device_header is not None:
+        end = process_header if process_header is not None else len(lines)
+        data_lines = []
+        for line in lines[device_header + 1 : end]:
+            cells = _cells(line)
+            if cells and not any("====" in cell or "----" in cell for cell in cells):
+                data_lines.append(cells)
+        i = 0
+        while i + 1 < len(data_lines):
+            first, second = data_lines[i], data_lines[i + 1]
+            identity = first[0].split() if first else []
+            detail_identity = second[0].split() if second else []
+            if len(identity) < 2 or not identity[0].isdigit():
+                i += 1
+                continue
+            index = int(identity[0])
+            chip = int(detail_identity[0]) if detail_identity and detail_identity[0].isdigit() else 0
+            summary = first[-1].split() if first else []
+            detail = second[-1] if second else ""
+            pairs = _memory_pairs(detail)
+            # On 910B, the final pair is HBM; on memory-only models it is the
+            # sole pair. Prefer the last pair with a non-zero capacity.
+            usable_pairs = [pair for pair in pairs if pair[1] > 0]
+            memory = usable_pairs[-1] if usable_pairs else (pairs[-1] if pairs else (None, None))
+            snapshot.devices.append(
+                DeviceInfo(
+                    index=index,
+                    chip=chip,
+                    name=" ".join(identity[1:]),
+                    health=first[1].split()[0] if len(first) > 1 and first[1] else "Unknown",
+                    bus_id=second[1].split()[0] if len(second) > 1 and second[1] else "-",
+                    power_w=_number(summary[0]) if len(summary) > 0 else None,
+                    temperature_c=_number(summary[1]) if len(summary) > 1 else None,
+                    utilization_percent=_number(detail.split()[0]) if detail.split() else None,
+                    memory_used_mb=memory[0],
+                    memory_total_mb=memory[1],
+                )
+            )
+            i += 2
+
+    if process_header is not None:
+        for line in lines[process_header + 1 :]:
+            cells = _cells(line)
+            if len(cells) < 4 or "No running processes" in line:
+                continue
+            identity = cells[0].split()
+            if len(identity) < 2 or not all(value.isdigit() for value in identity[:2]):
+                continue
+            pid = _number(cells[1], int)
+            if pid is None:
+                continue
+            container_pid = _number(cells[4], int) if len(cells) > 4 else None
+            snapshot.processes.append(
+                ProcessInfo(
+                    device_index=int(identity[0]),
+                    chip=int(identity[1]),
+                    pid=pid,
+                    name=cells[2] or "?",
+                    npu_memory_mb=_number(cells[3], int),
+                    container_pid=container_pid,
+                )
+            )
+    return snapshot
+
+
+class ProcfsEnricher:
+    def __init__(self, proc_root: Path = Path("/proc")) -> None:
+        self.proc_root = proc_root
+        self._ticks = os.sysconf("SC_CLK_TCK")
+        self._previous = {}  # pid -> process CPU ticks
+
+    def enrich(self, processes: Iterable[ProcessInfo], elapsed: Optional[float]) -> None:
+        current = {}
+        for process in processes:
+            root = self.proc_root / str(process.pid)
+            try:
+                # /proc/<pid>/stat encloses comm in parentheses; comm itself may
+                # contain spaces, so a plain split would shift utime/stime.
+                stat_text = (root / "stat").read_text(errors="replace")
+                closing_paren = stat_text.rfind(")")
+                stat = stat_text[closing_paren + 2 :].split()
+                total_ticks = int(stat[11]) + int(stat[12])
+                current[process.pid] = total_ticks
+                old = self._previous.get(process.pid)
+                if old is not None and elapsed and elapsed > 0:
+                    process.cpu_percent = max(0.0, (total_ticks - old) / self._ticks / elapsed * 100)
+            except (OSError, ValueError, IndexError):
+                pass
+            try:
+                fields = {}
+                for line in (root / "status").read_text(errors="replace").splitlines():
+                    if ":" in line:
+                        key, value = line.split(":", 1)
+                        fields[key] = value.strip()
+                uid = int(fields.get("Uid", "-1").split()[0])
+                try:
+                    import pwd
+
+                    process.username = pwd.getpwuid(uid).pw_name
+                except (KeyError, ImportError):
+                    process.username = str(uid)
+                rss = _number(fields.get("VmRSS", ""))
+                process.host_memory_mb = rss / 1024 if rss is not None else None
+            except (OSError, ValueError, IndexError):
+                pass
+            try:
+                command = (root / "cmdline").read_bytes().replace(b"\0", b" ").decode(errors="replace").strip()
+                process.command = command or process.name
+            except OSError:
+                process.command = process.name
+        self._previous = current
+
+
+class NpuSmiBackend:
+    def __init__(self, executable: Optional[str] = None, timeout: float = 5.0) -> None:
+        self.executable = executable or os.environ.get("NPUTOP_NPU_SMI") or shutil.which("npu-smi")
+        self.timeout = timeout
+        self.enricher = ProcfsEnricher()
+        self._last_time = None
+
+    def raw(self) -> str:
+        if not self.executable:
+            raise BackendError("npu-smi was not found in PATH (or set NPUTOP_NPU_SMI)")
+        try:
+            result = subprocess.run(
+                [self.executable, "info"],
+                check=False,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                text=True,
+                timeout=self.timeout,
+                env={**os.environ, "LC_ALL": "C"},
+            )
+        except (OSError, subprocess.TimeoutExpired) as exc:
+            raise BackendError(f"failed to run npu-smi: {exc}") from exc
+        if result.returncode != 0:
+            detail = result.stderr.strip() or result.stdout.strip() or f"exit code {result.returncode}"
+            raise BackendError(f"npu-smi failed: {detail}")
+        return result.stdout
+
+    def snapshot(self) -> Snapshot:
+        now = datetime.now(timezone.utc)
+        snapshot = parse_npu_smi(self.raw())
+        if not snapshot.devices:
+            raise BackendError("npu-smi returned no recognizable NPU devices")
+        elapsed = (now - self._last_time).total_seconds() if self._last_time else None
+        self.enricher.enrich(snapshot.processes, elapsed)
+        self._last_time = now
+        return snapshot
+
+
+def select_devices(snapshot: Snapshot, indexes: Optional[Sequence[int]]) -> Snapshot:
+    if indexes is None:
+        return snapshot
+    selected = set(indexes)
+    snapshot.devices = [device for device in snapshot.devices if device.index in selected]
+    snapshot.processes = [process for process in snapshot.processes if process.device_index in selected]
+    return snapshot

nptop-0.1.0/src/nputop/cli.py

@@ -0,0 +1,183 @@
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import select
+import signal
+import shutil
+import sys
+import termios
+import time
+import tty
+from contextlib import contextmanager
+from typing import Iterator, Optional, Sequence
+
+from . import __version__
+from .backend import BackendError, NpuSmiBackend, select_devices
+from .render import render, render_screen
+
+
+def _device_list(value: str):
+    try:
+        result = [int(item.strip()) for item in value.split(",") if item.strip()]
+    except ValueError as exc:
+        raise argparse.ArgumentTypeError("devices must be comma-separated integers") from exc
+    if not result or any(item < 0 for item in result):
+        raise argparse.ArgumentTypeError("at least one non-negative device index is required")
+    return result
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="nptop",
+        description="An nvitop-like interactive monitor for Ascend NPUs.",
+    )
+    parser.add_argument("-1", "--once", action="store_true", help="print one snapshot and exit")
+    parser.add_argument("-i", "--interval", type=float, default=2.0, help="refresh interval in seconds (default: 2)")
+    parser.add_argument("-d", "--device", type=_device_list, help="device indexes, for example 0,1,4")
+    parser.add_argument("--sort", choices=("memory", "cpu", "pid"), default="memory", help="process sort key")
+    parser.add_argument("--json", action="store_true", help="emit one JSON snapshot")
+    parser.add_argument("--raw", action="store_true", help="print raw npu-smi output for diagnostics")
+    parser.add_argument("--no-color", action="store_true", help="disable ANSI colors")
+    parser.add_argument("--timeout", type=float, default=5.0, help="npu-smi timeout in seconds")
+    parser.add_argument("-V", "--version", action="version", version=f"%(prog)s {__version__}")
+    return parser
+
+
+@contextmanager
+def _interactive_terminal(enabled: bool) -> Iterator[None]:
+    if not enabled:
+        yield
+        return
+    fd = sys.stdin.fileno()
+    previous = termios.tcgetattr(fd)
+    try:
+        tty.setcbreak(fd)
+        # Alternate screen, hidden cursor, and SGR mouse tracking. Wheel events
+        # then move our viewport instead of the terminal's scrollback buffer.
+        sys.stdout.write("\x1b[?1049h\x1b[?25l\x1b[?1000h\x1b[?1006h")
+        sys.stdout.flush()
+        yield
+    finally:
+        termios.tcsetattr(fd, termios.TCSADRAIN, previous)
+        sys.stdout.write("\x1b[?1006l\x1b[?1000l\x1b[?25h\x1b[?1049l")
+        sys.stdout.flush()
+
+
+def _read_key(timeout: float) -> Optional[str]:
+    ready, _, _ = select.select([sys.stdin], [], [], timeout)
+    if not ready:
+        return None
+    fd = sys.stdin.fileno()
+    sequence = os.read(fd, 64).decode(errors="ignore")
+    if not sequence.startswith("\x1b"):
+        return sequence
+    # Escape sequences arrive as a short burst in cbreak mode. Collect that
+    # burst without making a lone Escape key block the interface.
+    while sequence == "\x1b" or sequence.endswith(("[", ";")):
+        ready, _, _ = select.select([sys.stdin], [], [], 0.01)
+        if not ready:
+            break
+        sequence += os.read(fd, 64).decode(errors="ignore")
+    mapping = {
+        "\x1b[A": "up",
+        "\x1b[B": "down",
+        "\x1b[5~": "pageup",
+        "\x1b[6~": "pagedown",
+        "\x1b[H": "home",
+        "\x1b[F": "end",
+        "\x1bOH": "home",
+        "\x1bOF": "end",
+    }
+    if sequence in mapping:
+        return mapping[sequence]
+    if sequence.startswith("\x1b[<64;"):
+        return "wheelup"
+    if sequence.startswith("\x1b[<65;"):
+        return "wheeldown"
+    return "escape"
+
+
+def run(argv: Optional[Sequence[str]] = None) -> int:
+    args = build_parser().parse_args(argv)
+    if args.interval <= 0:
+        raise SystemExit("nptop: --interval must be greater than zero")
+    if args.timeout <= 0:
+        raise SystemExit("nptop: --timeout must be greater than zero")
+    backend = NpuSmiBackend(timeout=args.timeout)
+    if args.raw:
+        try:
+            sys.stdout.write(backend.raw())
+            return 0
+        except BackendError as exc:
+            print(f"nptop: {exc}", file=sys.stderr)
+            return 1
+
+    one_shot = args.once or args.json or not sys.stdout.isatty()
+    interactive = not one_shot and sys.stdin.isatty()
+    color = not args.no_color and "NO_COLOR" not in os.environ and (sys.stdout.isatty() or not one_shot)
+    sort = args.sort
+    scroll = 0
+    try:
+        with _interactive_terminal(interactive):
+            snapshot = select_devices(backend.snapshot(), args.device)
+            next_refresh = time.monotonic() + args.interval
+            while True:
+                if args.json:
+                    json.dump(snapshot.to_dict(), sys.stdout, ensure_ascii=False, indent=2)
+                    sys.stdout.write("\n")
+                    return 0
+                terminal = shutil.get_terminal_size((100, 24))
+                if one_shot:
+                    screen = render(snapshot, color=color, sort=sort, width=terminal.columns)
+                    print(screen)
+                    return 0
+                screen, max_scroll = render_screen(
+                    snapshot,
+                    color=color,
+                    sort=sort,
+                    width=terminal.columns,
+                    height=terminal.lines,
+                    scroll=scroll,
+                )
+                scroll = min(scroll, max_scroll)
+                sys.stdout.write("\x1b[H\x1b[2J" + screen)
+                sys.stdout.flush()
+                wait = max(0.0, next_refresh - time.monotonic())
+                key = _read_key(wait) if interactive else None
+                if key is None or key.lower() == "r":
+                    snapshot = select_devices(backend.snapshot(), args.device)
+                    next_refresh = time.monotonic() + args.interval
+                    continue
+                page = max(1, terminal.lines - 5)
+                if key.lower() == "q":
+                    return 0
+                if key in {"down", "j", "J", "wheeldown"}:
+                    scroll = min(max_scroll, scroll + (3 if key == "wheeldown" else 1))
+                elif key in {"up", "k", "K", "wheelup"}:
+                    scroll = max(0, scroll - (3 if key == "wheelup" else 1))
+                elif key in {"pagedown", " ", "f", "F"}:
+                    scroll = min(max_scroll, scroll + page)
+                elif key in {"pageup", "b", "B"}:
+                    scroll = max(0, scroll - page)
+                elif key in {"home", "g"}:
+                    scroll = 0
+                elif key in {"end", "G"}:
+                    scroll = max_scroll
+                elif key.lower() == "m":
+                    sort = "memory"
+                elif key.lower() == "c":
+                    sort = "cpu"
+                elif key.lower() == "p":
+                    sort = "pid"
+    except BackendError as exc:
+        print(f"nptop: {exc}", file=sys.stderr)
+        return 1
+    except KeyboardInterrupt:
+        return 130
+
+
+def main() -> int:
+    signal.signal(signal.SIGTERM, lambda *_: (_ for _ in ()).throw(KeyboardInterrupt()))
+    return run()

nptop-0.1.0/src/nputop/models.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional
+
+
+@dataclass
+class DeviceInfo:
+    index: int
+    chip: int = 0
+    name: str = "NPU"
+    health: str = "Unknown"
+    bus_id: str = "-"
+    power_w: Optional[float] = None
+    temperature_c: Optional[float] = None
+    utilization_percent: Optional[float] = None
+    memory_used_mb: Optional[int] = None
+    memory_total_mb: Optional[int] = None
+
+    @property
+    def memory_percent(self) -> Optional[float]:
+        if not self.memory_total_mb:
+            return None
+        return 100.0 * (self.memory_used_mb or 0) / self.memory_total_mb
+
+
+@dataclass
+class ProcessInfo:
+    device_index: int
+    chip: int
+    pid: int
+    name: str
+    npu_memory_mb: Optional[int] = None
+    container_pid: Optional[int] = None
+    username: str = "?"
+    cpu_percent: Optional[float] = None
+    host_memory_mb: Optional[float] = None
+    command: str = ""
+
+
+@dataclass
+class Snapshot:
+    devices: List[DeviceInfo] = field(default_factory=list)
+    processes: List[ProcessInfo] = field(default_factory=list)
+    driver_version: str = "unknown"
+    timestamp: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
+
+    def to_dict(self) -> Dict[str, Any]:
+        result = asdict(self)
+        result["timestamp"] = self.timestamp.isoformat()
+        for device, raw in zip(self.devices, result["devices"]):
+            raw["memory_percent"] = device.memory_percent
+        return result
+

nptop-0.1.0/src/nputop/render.py

@@ -0,0 +1,174 @@
+from __future__ import annotations
+
+import shutil
+import socket
+from typing import Iterable, List, Optional, Tuple
+
+from .models import DeviceInfo, ProcessInfo, Snapshot
+
+
+RESET = "\x1b[0m"
+COLORS = {
+    "dim": "\x1b[2m",
+    "bold": "\x1b[1m",
+    "cyan": "\x1b[36m",
+    "green": "\x1b[32m",
+    "yellow": "\x1b[33m",
+    "red": "\x1b[31m",
+}
+
+
+def _paint(text: str, color: str, enabled: bool) -> str:
+    return f"{COLORS[color]}{text}{RESET}" if enabled else text
+
+
+def _value(value, suffix: str = "", decimals: int = 0) -> str:
+    if value is None:
+        return "-"
+    return f"{value:.{decimals}f}{suffix}"
+
+
+def _clip(value: str, width: int) -> str:
+    if len(value) <= width:
+        return value
+    return value[: max(0, width - 1)] + "…"
+
+
+def _bar(percent: Optional[float], width: int, color: bool) -> str:
+    if percent is None:
+        return _paint("·" * width, "dim", color)
+    value = min(100.0, max(0.0, percent))
+    filled = round(value * width / 100)
+    text = "█" * filled + "░" * (width - filled)
+    level = "red" if value >= 90 else "yellow" if value >= 70 else "green"
+    return _paint(text, level, color)
+
+
+def _memory_gib(device: DeviceInfo) -> str:
+    if device.memory_used_mb is None or device.memory_total_mb is None:
+        return "-"
+    return f"{device.memory_used_mb / 1024:.1f}/{device.memory_total_mb / 1024:.0f}G"
+
+
+def _device_line(device: DeviceInfo, color: bool, width: int) -> str:
+    utilization = device.utilization_percent
+    memory_percent = device.memory_percent
+    health_color = "green" if device.health.upper() in {"OK", "NORMAL"} else "red"
+    health = _paint(f"{_clip(device.health, 4):<4}", health_color, color)
+
+    if width < 72:
+        # Both meters remain visible even on narrow terminals. Secondary fields
+        # are omitted before either requested progress bar is removed.
+        bar_width = max(3, min(7, (width - 31) // 2))
+        return (
+            f" #{device.index:<2} A {_bar(utilization, bar_width, color)} {_value(utilization, '%'):>4} "
+            f"M {_bar(memory_percent, bar_width, color)} {_value(memory_percent, '%'):>4} "
+            f"{_memory_gib(device):>9}"
+        )
+
+    bar_width = 12 if width >= 110 else 7 if width >= 86 else 5
+    name_width = 12 if width >= 100 else 8
+    return (
+        f" {device.index:>2} {_clip(device.name, name_width):<{name_width}} {health} "
+        f"{_value(device.temperature_c):>3}C {_value(device.power_w, '', 0):>4}W  "
+        f"AIC {_bar(utilization, bar_width, color)} {_value(utilization, '%'):>4}  "
+        f"MEM {_bar(memory_percent, bar_width, color)} {_value(memory_percent, '%'):>4} "
+        f"{_memory_gib(device):>9}"
+    )
+
+
+def _sort_processes(processes: Iterable[ProcessInfo], key: str) -> List[ProcessInfo]:
+    if key == "pid":
+        return sorted(processes, key=lambda process: process.pid)
+    if key == "cpu":
+        return sorted(processes, key=lambda process: process.cpu_percent or -1, reverse=True)
+    return sorted(processes, key=lambda process: process.npu_memory_mb or -1, reverse=True)
+
+
+def _content_lines(snapshot: Snapshot, color: bool, sort: str, width: int) -> List[str]:
+    device_heading = " NPU DEVICE       STAT TEMP POWER   AICORE USAGE        MEMORY USAGE         USED/TOTAL"
+    lines = [
+        _paint(_clip(device_heading, width), "cyan", color)
+    ]
+    lines.extend(_device_line(device, color, width) for device in snapshot.devices)
+    lines.append("")
+    lines.append(_paint(f" Processes ({len(snapshot.processes)})  sort={sort}", "bold", color))
+    process_heading = " NPU   PID      USER         CPU%   HOST MEM   NPU MEM   COMMAND"
+    lines.append(_paint(_clip(process_heading, width), "cyan", color))
+    command_width = max(8, width - 62)
+    for process in _sort_processes(snapshot.processes, sort):
+        command = process.command or process.name
+        lines.append(
+            f" {process.device_index:>3} {process.pid:>8}  {_clip(process.username, 12):<12} "
+            f"{_value(process.cpu_percent, '', 1):>6}  "
+            f"{_value(process.host_memory_mb, 'M', 1):>9}  "
+            f"{_value(process.npu_memory_mb, 'M'):>8}   {_clip(command, command_width)}"
+        )
+    if not snapshot.processes:
+        lines.append(_paint(" No running NPU processes", "dim", color))
+    return lines
+
+
+def _header(snapshot: Snapshot, color: bool, width: int) -> List[str]:
+    title = f"nptop  {socket.gethostname()}  npu-smi {snapshot.driver_version}"
+    stamp = snapshot.timestamp.astimezone().strftime("%Y-%m-%d %H:%M:%S")
+    if len(title) + len(stamp) + 1 > width:
+        title = _clip(title, max(8, width - len(stamp) - 1))
+    gap = max(1, width - len(title) - len(stamp))
+    return [
+        _paint(title, "bold", color) + " " * gap + _paint(stamp, "dim", color),
+        "─" * width,
+    ]
+
+
+def render_screen(
+    snapshot: Snapshot,
+    *,
+    color: bool = True,
+    sort: str = "memory",
+    width: int = 100,
+    height: int = 24,
+    scroll: int = 0,
+) -> Tuple[str, int]:
+    """Render one fixed terminal frame and return it with its max scroll offset."""
+    width = max(40, width)
+    height = max(6, height)
+    content = _content_lines(snapshot, color, sort, width)
+    viewport_height = height - 3  # two header rows and one status/footer row
+    max_scroll = max(0, len(content) - viewport_height)
+    scroll = min(max(0, scroll), max_scroll)
+    visible = content[scroll : scroll + viewport_height]
+    visible.extend([""] * (viewport_height - len(visible)))
+    first = scroll + 1 if content else 0
+    last = min(scroll + viewport_height, len(content))
+    keys = "↑/k ↓/j scroll  PgUp/PgDn  Home/End  r refresh  m/c/p sort  q quit"
+    position = f"[{first}-{last}/{len(content)}]"
+    footer_space = max(1, width - len(position) - 1)
+    visible_keys = _clip(keys, footer_space)
+    footer = _paint(visible_keys, "dim", color)
+    footer += " " * max(1, width - len(visible_keys) - len(position)) + position
+    return "\n".join(_header(snapshot, color, width) + visible + [footer]), max_scroll
+
+
+def render(
+    snapshot: Snapshot,
+    *,
+    color: bool = True,
+    sort: str = "memory",
+    width: Optional[int] = None,
+    height: Optional[int] = None,
+    scroll: int = 0,
+) -> str:
+    """Render a full report, or a scrollable frame when ``height`` is provided."""
+    width = max(40, width or shutil.get_terminal_size((100, 24)).columns)
+    if height is not None:
+        return render_screen(
+            snapshot,
+            color=color,
+            sort=sort,
+            width=width,
+            height=height,
+            scroll=scroll,
+        )[0]
+    content = _content_lines(snapshot, color, sort, width)
+    return "\n".join(_header(snapshot, color, width) + content)

nptop-0.1.0/tests/test_backend.py

@@ -0,0 +1,56 @@
+from pathlib import Path
+
+from nputop.backend import ProcfsEnricher, parse_npu_smi, select_devices
+from nputop.models import ProcessInfo
+
+
+FIXTURE = Path(__file__).parent / "fixtures" / "npu_smi_910b.txt"
+
+
+def test_parse_devices_and_processes():
+    snapshot = parse_npu_smi(FIXTURE.read_text())
+
+    assert snapshot.driver_version == "26.0.rc2"
+    assert len(snapshot.devices) == 2
+    first = snapshot.devices[0]
+    assert (first.index, first.chip, first.name) == (0, 0, "910B2C")
+    assert first.health == "OK"
+    assert first.power_w == 92.1
+    assert first.temperature_c == 32
+    assert first.utilization_percent == 17
+    assert (first.memory_used_mb, first.memory_total_mb) == (3419, 65536)
+
+    process = snapshot.processes[0]
+    assert (process.device_index, process.pid, process.name) == (0, 12345, "python3")
+    assert process.npu_memory_mb == 2048
+    assert process.container_pid == 99
+
+
+def test_select_devices_also_filters_processes():
+    snapshot = select_devices(parse_npu_smi(FIXTURE.read_text()), [1])
+    assert [device.index for device in snapshot.devices] == [1]
+    assert snapshot.processes == []
+
+
+def test_procfs_handles_process_names_with_spaces(tmp_path):
+    proc = tmp_path / "42"
+    proc.mkdir()
+    # Fields after comm begin at state (field 3); utime/stime are offsets 11/12.
+    proc.joinpath("stat").write_text(
+        "42 (worker with spaces) S 0 0 0 0 0 0 0 0 0 0 100 50 0 0 0 0 0 0 0\n"
+    )
+    proc.joinpath("status").write_text("Uid:\t0 0 0 0\nVmRSS:\t2048 kB\n")
+    proc.joinpath("cmdline").write_bytes(b"python\0train.py\0")
+    process = ProcessInfo(device_index=0, chip=0, pid=42, name="worker")
+
+    enricher = ProcfsEnricher(tmp_path)
+    enricher.enrich([process], elapsed=None)
+    proc.joinpath("stat").write_text(
+        "42 (worker with spaces) S 0 0 0 0 0 0 0 0 0 0 200 100 0 0 0 0 0 0 0\n"
+    )
+    enricher.enrich([process], elapsed=1.0)
+
+    assert process.cpu_percent is not None
+    assert process.cpu_percent > 0
+    assert process.host_memory_mb == 2
+    assert process.command == "python train.py"

nptop-0.1.0/tests/test_cli.py

@@ -0,0 +1,18 @@
+import json
+from pathlib import Path
+
+from nputop.cli import run
+
+
+def test_json_mode_with_fake_npu_smi(tmp_path, monkeypatch, capsys):
+    fixture = Path(__file__).parent / "fixtures" / "npu_smi_910b.txt"
+    executable = tmp_path / "npu-smi"
+    executable.write_text("#!/bin/sh\nexec /bin/cat \"$NPUTOP_FIXTURE\"\n")
+    executable.chmod(0o755)
+    monkeypatch.setenv("NPUTOP_NPU_SMI", str(executable))
+    monkeypatch.setenv("NPUTOP_FIXTURE", str(fixture))
+
+    assert run(["--json", "--device", "0"]) == 0
+    result = json.loads(capsys.readouterr().out)
+    assert [item["index"] for item in result["devices"]] == [0]
+

nptop-0.1.0/tests/test_render.py

@@ -0,0 +1,63 @@
+from pathlib import Path
+
+from nputop.backend import parse_npu_smi
+from nputop.models import DeviceInfo, ProcessInfo
+from nputop.render import render, render_screen
+
+
+def test_plain_render_contains_device_and_process():
+    fixture = Path(__file__).parent / "fixtures" / "npu_smi_910b.txt"
+    output = render(parse_npu_smi(fixture.read_text()), color=False, width=100)
+    assert "nptop" in output
+    assert "910B2C" in output
+    assert "3.3/64G" in output
+    assert "AIC" in output
+    assert "MEM" in output
+    assert "█" in output
+    assert "12345" in output
+    assert "python3" in output
+    assert "\x1b[" not in output
+
+
+def test_sixteen_devices_start_at_top_and_processes_can_scroll():
+    fixture = Path(__file__).parent / "fixtures" / "npu_smi_910b.txt"
+    snapshot = parse_npu_smi(fixture.read_text())
+    template = snapshot.devices[0]
+    snapshot.devices = [
+        DeviceInfo(
+            index=index,
+            chip=template.chip,
+            name=template.name,
+            health=template.health,
+            power_w=template.power_w,
+            temperature_c=template.temperature_c,
+            utilization_percent=template.utilization_percent,
+            memory_used_mb=template.memory_used_mb,
+            memory_total_mb=template.memory_total_mb,
+        )
+        for index in range(16)
+    ]
+    snapshot.processes = [
+        ProcessInfo(
+            device_index=index,
+            chip=0,
+            pid=1000 + index,
+            name="python",
+            npu_memory_mb=2048,
+            username="tester",
+            command=f"python train.py --rank {index}",
+        )
+        for index in range(16)
+    ]
+    top, max_scroll = render_screen(snapshot, color=False, width=80, height=24, scroll=0)
+    bottom, _ = render_screen(snapshot, color=False, width=80, height=24, scroll=max_scroll)
+
+    assert len(top.splitlines()) == 24
+    assert max(map(len, top.splitlines())) <= 80
+    assert max_scroll > 0
+    for index in range(16):
+        assert f" {index:>2} 910B2C" in top
+    assert "  0 910B2C" not in bottom
+    assert "1015" in bottom
+    assert "[1-21/36]" in top
+    assert "q quit" in top