Skip to content

"CLI-Anything: Making ALL Software Agent-Native" -- CLI-Hub: https://clianything.cc/

Python

Add Nsight Graphics docs and GPU Trace summary

aimidi57bd6a5ce9b8
diff --git a/.gitignore b/.gitignore
index 84aad877f..acdc15011 100644
--- a/.gitignore
+++ b/.gitignore
@@ -225,6 +225,8 @@
!/safari/
!/safari/agent-harness/
!/nsight-graphics/agent-harness/
+!/nsight-graphics/README.md
+!/nsight-graphics/README_CN.md
# Step 7: Ignore build artifacts within allowed dirs
**/__pycache__/
diff --git a/README.md b/README.md
index f739d72d3..385eea4d7 100644
--- a/README.md
+++ b/README.md
@@ -15,7 +15,7 @@ CLI-Anything: Bridging the Gap Between AI Agents and the World's Software</stron
<a href="#-quick-start"><img src="https://img.shields.io/badge/Quick_Start-5_min-blue?style=for-the-badge" alt="Quick Start"></a>
<a href="https://hkuds.github.io/CLI-Anything/"><img src="https://img.shields.io/badge/CLI_Hub-Browse_%26_Install-ff69b4?style=for-the-badge" alt="CLI Hub"></a>
<a href="#-demonstrations"><img src="https://img.shields.io/badge/Demos-16_Apps-green?style=for-the-badge" alt="Demos"></a>
- <a href="#-test-results"><img src="https://img.shields.io/badge/Tests-2%2C130_Passing-brightgreen?style=for-the-badge" alt="Tests"></a>
+ <a href="#-test-results"><img src="https://img.shields.io/badge/Tests-2%2C162_Passing-brightgreen?style=for-the-badge" alt="Tests"></a>
<a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow?style=for-the-badge" alt="License"></a>
</p>
@@ -566,7 +566,7 @@ The catalog auto-updates whenever `registry.json` changes — new community CLIs
| **📐 Diagramming & Visualization** | Create and manipulate diagrams, flowcharts, architecture diagrams, and visual documentation programmatically | Draw.io (diagrams.net), Mermaid, PlantUML, Excalidraw, yEd |
| **🌐 Network & Infrastructure** | Manage network services, DNS, ad-blocking, and infrastructure through structured CLI commands | AdGuardHome |
| **🧪 Testing & Mocking** | Control HTTP mock servers, manage test stubs, record and replay API traffic for integration testing | **[WireMock](https://wiremock.org)** |
-| **🔬 Graphics & GPU Debugging** | Analyze GPU frame captures, inspect pipeline state, export shaders, diff rendering state, and orchestrate Nsight Graphics captures | RenderDoc, Nsight Graphics |
+| **🔬 Graphics & GPU Debugging** | Analyze GPU frame captures, inspect pipeline state, export shaders, diff rendering state, orchestrate Nsight Graphics captures, and summarize GPU Trace hotspots | RenderDoc, Nsight Graphics |
| **🎬 Video & Subtitles** | Transcribe speech, translate subtitles, burn styled captions into video — full captioning pipeline | VideoCaptioner |
| **🔍 AI-Native Search** | Neural and deep web search with structured content retrieval through embedding-based APIs | [Exa](https://exa.ai) |
| **✨ AI Content Generation** | Generate professional deliverables (slides, docs, diagrams, websites, research reports) through AI-powered cloud APIs | [AnyGen](https://www.anygen.io), Gamma, Beautiful.ai, Tome |
@@ -586,7 +586,7 @@ AI agents are great at reasoning but terrible at using real professional softwar
| 💸 "UI automation breaks constantly" | No screenshots, no clicking, no RPA fragility. Pure command-line reliability with structured interfaces |
| 📊 "Agents need structured data" | Built-in JSON output for seamless agent consumption + human-readable formats for debugging |
| 🔧 "Custom integrations are expensive" | One Claude plugin auto-generates CLIs for ANY codebase through proven 7-phase pipeline |
-| ⚡ "Prototype vs Production gap" | 1,839+ tests with real software validation. Battle-tested across 16 major applications |
+| ⚡ "Prototype vs Production gap" | 2,162+ tests with real software validation. Battle-tested across 16 major applications |
---
@@ -956,11 +956,13 @@ Each application received complete, production-ready CLI interfaces — not demo
<td><code>cli-anything-godot</code></td>
<td>Godot 4.x headless subprocess</td>
<td align="center">✅ 24</td>
-<td align="center"><strong>🟩 Nsight Graphics</strong></td>
+</tr>
+<tr>
+<td align="center"><strong>🟩 <a href="nsight-graphics/">Nsight Graphics CLI</a></strong></td>
<td>GPU Debugging & Profiling</td>
<td><code>cli-anything-nsight-graphics</code></td>
-<td>Official ngfx / ngfx-capture orchestration</td>
-<td align="center">✅ <a href="nsight-graphics/agent-harness/">New</a></td>
+<td>Official ngfx / ngfx-capture orchestration + GPU Trace summary</td>
+<td align="center">✅ 32</td>
</tr>
<tr>
<td align="center"><strong>🅲🅲 CloudCompare</strong></td>
@@ -985,11 +987,11 @@ Each application received complete, production-ready CLI interfaces — not demo
</tr>
<tr>
<td align="center" colspan="4"><strong>Total</strong></td>
-<td align="center"><strong>✅ 2,130</strong></td>
+<td align="center"><strong>✅ 2,162</strong></td>
</tr>
</table>
-> **100% pass rate** across all 2,130 tests — 1,551 unit tests + 560 end-to-end tests + 19 Node.js tests.
+> **100% pass rate** across all 2,162 tests — 1,582 unit tests + 561 end-to-end tests + 19 Node.js tests.
---
@@ -1027,10 +1029,11 @@ ollama 98 passed ✅ (87 unit + 11 e2e)
sketch 19 passed ✅ (19 jest, Node.js)
renderdoc 59 passed ✅ (45 unit + 14 e2e)
cloudcompare 88 passed ✅ (49 unit + 39 e2e)
+nsight-graphics 32 passed ✅ (31 unit + 1 e2e)
openscreen 101 passed ✅ (78 unit + 23 e2e)
cloudanalyzer 14 passed ✅ (7 unit + 7 e2e)
──────────────────────────────────────────────────────────────────────────────
-TOTAL 2,120 passed ✅ 100% pass rate
+TOTAL 2,162 passed ✅ 100% pass rate
```
---
@@ -1109,7 +1112,7 @@ cli-anything/
├── ☁️ cloudcompare/agent-harness/ # CloudCompare CLI (88 tests)
├── 🔍 exa/agent-harness/ # Exa CLI (40 tests)
└── ⛅ cloudanalyzer/agent-harness/ # CloudAnalyzer CLI (14 tests)
-├── 🟩 nsight-graphics/agent-harness/ # Nsight Graphics CLI (new)
+├── 🟩 nsight-graphics/ # Nsight Graphics CLI (32 tests)
```
Each `agent-harness/` contains an installable Python package under `cli_anything.<software>/` with Click CLI, core modules, utils (including `repl_skin.py` and backend wrapper), and comprehensive tests.
@@ -1335,7 +1338,7 @@ MIT License — free to use, modify, and distribute.
**CLI-Anything** — *Make any software with a codebase Agent-native.*
-<sub>A methodology for the age of AI agents | 16 professional software demos | 1,839 passing tests</sub>
+<sub>A methodology for the age of AI agents | 16 professional software demos | 2,162 passing tests</sub>
<br>
diff --git a/nsight-graphics/README.md b/nsight-graphics/README.md
new file mode 100644
index 000000000..0c9003c38
--- /dev/null
+++ b/nsight-graphics/README.md
@@ -0,0 +1,81 @@
+# Nsight Graphics
+
+This directory contains the CLI-Anything integration for **NVIDIA Nsight Graphics**.
+
+It is designed for humans coordinating AI agents as well as for agents calling
+the harness directly.
+
+## What This Integration Does
+
+- detects installed Nsight Graphics versions
+- selects a specific install with `--nsight-path`
+- launches a target or attaches to a running PID
+- captures a frame
+- collects a GPU Trace report
+- summarizes exported GPU Trace timing results
+- generates a C++ capture
+
+## Recommended Human-to-AI Prompt Format
+
+Give the AI these fields explicitly:
+
+```text
+Nsight version: 2026.1.0
+Program: D:/path/to/YourApp.exe
+Working dir: D:/path/to
+Args: "D:\path\project.uproject" -dx12 -log -newconsole
+Action: Graphics Capture / GPU Trace / C++ Capture
+Trigger: after 10 seconds / frame 300 / I will press F11
+Output: capture path / trace path / top 10 GPU hotspots / summary
+```
+
+## Prompt Examples
+
+### Inspect installations
+
+```text
+Use the Nsight Graphics harness. List installed versions, tell me which one is selected, and switch to 2026.1.0 if available.
+```
+
+### One-step GPU Trace summary
+
+```text
+Use Nsight Graphics 2026.1.0 and run a GPU Trace on this executable.
+Wait for me to press F11 manually.
+After it finishes, give me:
+- frame time
+- estimated FPS
+- draw count and dispatch count
+- top 10 GPU events
+- short diagnosis of what looks expensive
+Program: D:/path/to/App.exe
+Working dir: D:/path/to
+Args: ...
+```
+
+### Automatic frame capture
+
+```text
+Launch this program under Nsight Graphics and automatically capture one frame after 10 seconds. Return the capture file path.
+```
+
+## Operator Notes
+
+- If multiple Nsight versions are installed, pin one with `--nsight-path`
+ when reproducibility matters.
+- For one-step performance triage, prefer:
+
+```bash
+cli-anything-nsight-graphics gpu-trace capture --auto-export --summarize
+```
+
+- If a running process is already attached to a different Nsight activity,
+ ask the AI to launch a fresh process for GPU Trace instead of reusing it.
+- This harness is Windows-first and wraps the official CLI tools, not the full GUI.
+
+## Related Docs
+
+- Chinese guide: [README_CN.md](D:\code\D5\CLI-Anything-nsight-graphics-dev\nsight-graphics\README_CN.md)
+- Package usage: [agent-harness/cli_anything/nsight_graphics/README.md](D:\code\D5\CLI-Anything-nsight-graphics-dev\nsight-graphics\agent-harness\cli_anything\nsight_graphics\README.md)
+- Software notes: [agent-harness/NSIGHT_GRAPHICS.md](D:\code\D5\CLI-Anything-nsight-graphics-dev\nsight-graphics\agent-harness\NSIGHT_GRAPHICS.md)
+- Agent skill: [agent-harness/cli_anything/nsight_graphics/skills/SKILL.md](D:\code\D5\CLI-Anything-nsight-graphics-dev\nsight-graphics\agent-harness\cli_anything\nsight_graphics\skills\SKILL.md)
diff --git a/nsight-graphics/README_CN.md b/nsight-graphics/README_CN.md
new file mode 100644
index 000000000..939455906
--- /dev/null
+++ b/nsight-graphics/README_CN.md
@@ -0,0 +1,78 @@
+# Nsight Graphics
+
+这个目录包含 **NVIDIA Nsight Graphics** 的 CLI-Anything 集成。
+
+它既面向直接调用 harness 的 AI,也面向“由人来调度 AI 使用这个能力”的工作流。
+
+## 这个能力可以做什么
+
+- 检测本机安装了哪些 Nsight Graphics 版本
+- 用 `--nsight-path` 显式选择某个安装版本
+- 启动目标程序或附加到已有 PID
+- 抓取一帧图形捕获
+- 收集一轮 GPU Trace
+- 自动总结 GPU Trace 导出的耗时结果
+- 生成 C++ Capture
+
+## 推荐的人类提示格式
+
+建议把这些信息明确告诉 AI:
+
+```text
+Nsight版本:2026.1.0
+程序:D:/path/to/YourApp.exe
+工作目录:D:/path/to
+参数:"D:\path\project.uproject" -dx12 -log -newconsole
+动作:Graphics Capture / GPU Trace / C++ Capture
+触发方式:10秒后 / 第300帧 / 我会按 F11
+输出:capture 路径 / trace 路径 / Top10 GPU 热点 / 总结
+```
+
+## 提示示例
+
+### 查看安装版本
+
+```text
+使用 Nsight Graphics harness,列出本机已安装版本,告诉我当前默认选中哪个,如果有 2026.1.0 就切过去。
+```
+
+### 一步式 GPU Trace 总结
+
+```text
+使用 Nsight Graphics 2026.1.0 对这个程序做一轮 GPU Trace。
+等我手动按 F11 触发。
+结束后给我:
+- 帧时间
+- 估算 FPS
+- draw count 和 dispatch count
+- 最耗时前 10 个 GPU 事件
+- 一段简短诊断,说明主要瓶颈在哪里
+程序:D:/path/to/App.exe
+工作目录:D:/path/to
+参数:...
+```
+
+### 自动抓帧
+
+```text
+用 Nsight Graphics 启动这个程序,10 秒后自动抓 1 帧,并把 capture 文件路径返回给我。
+```
+
+## 使用建议
+
+- 多版本共存时,建议始终用 `--nsight-path` 固定版本。
+- 如果你想让 AI 一步完成“抓 trace + 导出 + 总结”,优先让它使用:
+
+```bash
+cli-anything-nsight-graphics gpu-trace capture --auto-export --summarize
+```
+
+- 如果目标进程已经挂在其他 Nsight activity 上,建议让 AI 新起一个进程来跑 GPU Trace。
+- 这个 harness 当前是 Windows-first,封装的是官方 CLI,不是完整 GUI 的全部功能。
+
+## 相关文档
+
+- 英文说明:[README.md](D:\code\D5\CLI-Anything-nsight-graphics-dev\nsight-graphics\README.md)
+- 包内使用说明:[agent-harness/cli_anything/nsight_graphics/README.md](D:\code\D5\CLI-Anything-nsight-graphics-dev\nsight-graphics\agent-harness\cli_anything\nsight_graphics\README.md)
+- 软件说明:[agent-harness/NSIGHT_GRAPHICS.md](D:\code\D5\CLI-Anything-nsight-graphics-dev\nsight-graphics\agent-harness\NSIGHT_GRAPHICS.md)
+- Agent 技能:[agent-harness/cli_anything/nsight_graphics/skills/SKILL.md](D:\code\D5\CLI-Anything-nsight-graphics-dev\nsight-graphics\agent-harness\cli_anything\nsight_graphics\skills\SKILL.md)
diff --git a/nsight-graphics/agent-harness/HARNESS.md b/nsight-graphics/agent-harness/HARNESS.md
index 8267c0fa3..c6482b997 100644
--- a/nsight-graphics/agent-harness/HARNESS.md
+++ b/nsight-graphics/agent-harness/HARNESS.md
@@ -55,7 +55,7 @@ agent-harness/
| `doctor` | `info` |
| `launch` | `detached`, `attach` |
| `frame` | `capture` |
-| `gpu-trace` | `capture` |
+| `gpu-trace` | `capture`, `summarize` |
| `cpp` | `capture` |
## Backend Strategy
diff --git a/nsight-graphics/agent-harness/NSIGHT_GRAPHICS.md b/nsight-graphics/agent-harness/NSIGHT_GRAPHICS.md
index 73221ed4f..e558e9e19 100644
--- a/nsight-graphics/agent-harness/NSIGHT_GRAPHICS.md
+++ b/nsight-graphics/agent-harness/NSIGHT_GRAPHICS.md
@@ -21,6 +21,7 @@ This harness targets the official command-line interfaces rather than the GUI.
- attach to a running PID with an activity
- Frame Debugger capture orchestration
- GPU Trace capture orchestration
+- GPU Trace export summarization
- Generate C++ Capture orchestration
- artifact discovery in output directories
@@ -29,6 +30,7 @@ This harness targets the official command-line interfaces rather than the GUI.
- replay-helper public commands
- pipeline/resource/shader inspection APIs
- deep analysis comparable to RenderDoc's Python bindings
+- full GUI-level replay investigation and editing workflows
## Compatibility Notes
@@ -37,3 +39,12 @@ This harness targets the official command-line interfaces rather than the GUI.
- On newer installs, `ngfx-capture` / `ngfx-replay` may exist alongside `ngfx`.
- This harness prefers capability detection over hard-coded version branching.
- `--nsight-path` can explicitly select one installation when multiple versions coexist.
+
+## AI Operator Workflow
+
+For one-step performance triage, the intended flow is:
+
+1. run `doctor versions`
+2. optionally pin a version with `--nsight-path`
+3. run `gpu-trace capture --auto-export --summarize`
+4. inspect the returned summary and the exported `.xls` tables if you need more detail
diff --git a/nsight-graphics/agent-harness/cli_anything/nsight_graphics/README.md b/nsight-graphics/agent-harness/cli_anything/nsight_graphics/README.md
index 9cff828c4..ba2d302d2 100644
--- a/nsight-graphics/agent-harness/cli_anything/nsight_graphics/README.md
+++ b/nsight-graphics/agent-harness/cli_anything/nsight_graphics/README.md
@@ -8,7 +8,7 @@ terminal:
- installation and capability probing
- detached launch and PID attach
- Frame Debugger capture
-- GPU Trace capture and auto-export
+- GPU Trace capture, auto-export, and summary generation
- Generate C++ Capture
It does not provide RenderDoc-style offline inspection of shaders, pipeline
@@ -85,7 +85,15 @@ cli-anything-nsight-graphics --output-dir D:\traces gpu-trace capture ^
--exe "C:\VulkanSDK\1.3.290.0\Bin\vkcube.exe" ^
--start-after-ms 1000 ^
--limit-to-frames 1 ^
- --auto-export
+ --auto-export ^
+ --summarize
+```
+
+### Summarize an existing GPU Trace export
+
+```bash
+cli-anything-nsight-graphics gpu-trace summarize ^
+ --input-dir D:\traces
```
### Generate a C++ capture
@@ -119,7 +127,8 @@ cli-anything-nsight-graphics --output-dir D:\cpp cpp capture ^
| `launch` | `detached` | Launch a target under Nsight without blocking the CLI |
| `launch` | `attach` | Attach Nsight to a running PID |
| `frame` | `capture` | Trigger a Frame Debugger capture |
-| `gpu-trace` | `capture` | Trigger a GPU Trace capture |
+| `gpu-trace` | `capture` | Trigger a GPU Trace capture and optionally summarize the exported result |
+| `gpu-trace` | `summarize` | Summarize an existing GPU Trace export directory |
| `cpp` | `capture` | Trigger Generate C++ Capture |
## JSON Output
@@ -139,6 +148,14 @@ Capture-producing commands also include:
- `output_dir`
- `artifacts`
+When `gpu-trace capture --summarize` is used, the result also includes:
+
+- `summary.frame_time_ms`
+- `summary.fps_estimate`
+- `summary.metrics`
+- `summary.top_events`
+- `summary.highlights`
+
## Environment Variables
| Variable | Purpose |
@@ -175,3 +192,23 @@ not currently have a discovered Nsight executable path. They are useful for
diagnosis, but not enough by themselves to launch captures. The harness also
scans standard `Program Files` locations on all fixed Windows drives, so
non-`C:` installs can still be promoted to normal filesystem-backed entries.
+
+## One-Step GPU Trace Triage
+
+If you want the harness to behave like a single-shot performance assistant,
+prefer this pattern:
+
+```bash
+cli-anything-nsight-graphics --output-dir D:\traces gpu-trace capture ^
+ --exe "C:\Path\To\App.exe" ^
+ --start-after-hotkey ^
+ --limit-to-frames 1 ^
+ --auto-export ^
+ --summarize
+```
+
+That gives you:
+
+- the `.ngfx-gputrace` artifact
+- exported `FRAME.xls`, `GPUTRACE_FRAME.xls`, and `D3DPERF_EVENTS.xls`
+- a parsed summary with frame time, estimated FPS, selected counters, and top GPU events
diff --git a/nsight-graphics/agent-harness/cli_anything/nsight_graphics/core/gpu_trace.py b/nsight-graphics/agent-harness/cli_anything/nsight_graphics/core/gpu_trace.py
index 56b88f10d..2795c6fa8 100644
--- a/nsight-graphics/agent-harness/cli_anything/nsight_graphics/core/gpu_trace.py
+++ b/nsight-graphics/agent-harness/cli_anything/nsight_graphics/core/gpu_trace.py
@@ -1,11 +1,200 @@
-"""GPU Trace orchestration."""
+"""GPU Trace orchestration and export summarization."""
from __future__ import annotations
-from typing import Sequence
+import csv
+from pathlib import Path
+from typing import Any, Sequence
from cli_anything.nsight_graphics.utils import nsight_graphics_backend as backend
+SUMMARY_METRICS = {
+ "draw_count": "fe__draw_count.sum",
+ "dispatch_count": "gr__dispatch_count.sum",
+ "graphics_engine_active_pct": "gr__cycles_active.avg.pct_of_peak_sustained_elapsed",
+ "compute_queue_sync_active_pct": "gr__compute_cycles_active_queue_sync.avg.pct_of_peak_sustained_elapsed",
+ "compute_queue_async_active_pct": "gr__compute_cycles_active_queue_async.avg.pct_of_peak_sustained_elapsed",
+ "sm_throughput_pct": "sm__throughput.avg.pct_of_peak_sustained_elapsed",
+ "l1tex_throughput_pct": "l1tex__throughput.avg.pct_of_peak_sustained_elapsed",
+ "l2_throughput_pct": "lts__throughput.avg.pct_of_peak_sustained_elapsed",
+ "dram_throughput_pct": "dramc__throughput.avg.pct_of_peak_sustained_elapsed",
+ "pcie_throughput_pct": "pcie__throughput.avg.pct_of_peak_sustained_elapsed",
+}
+
+
+def _find_first(output_dir: str, name: str) -> str | None:
+ """Find the first matching file under an export directory."""
+ matches = sorted(Path(output_dir).rglob(name))
+ return str(matches[0]) if matches else None
+
+
+def _read_kv_file(path: str) -> dict[str, str]:
+ """Read a simple tab-separated key/value file."""
+ data: dict[str, str] = {}
+ with open(path, "r", encoding="utf-8-sig", errors="replace") as handle:
+ for raw in handle:
+ line = raw.strip()
+ if not line or "\t" not in line:
+ continue
+ key, value = line.split("\t", 1)
+ data[key.strip()] = value.strip()
+ return data
+
+
+def _read_event_rows(path: str) -> list[dict[str, str]]:
+ """Read D3DPERF event rows from the exported TSV."""
+ with open(path, "r", encoding="utf-8-sig", errors="replace", newline="") as handle:
+ reader = csv.DictReader(handle, delimiter="\t")
+ rows = []
+ for row in reader:
+ event_text = (row.get("event_text") or "").rstrip()
+ time_ms = (row.get("time_ms") or "").strip()
+ if not event_text or not time_ms:
+ continue
+ rows.append({"event_text": event_text, "time_ms": time_ms})
+ return rows
+
+
+def _safe_float(value: str | None) -> float | None:
+ """Convert a string to float when possible."""
+ if value is None:
+ return None
+ try:
+ return float(value)
+ except (TypeError, ValueError):
+ return None
+
+
+def _safe_int(value: float | None) -> int | None:
+ """Convert a float to int when available."""
+ if value is None:
+ return None
+ return int(round(value))
+
+
+def _pick_metric(metrics: dict[str, str], needle: str) -> float | None:
+ """Find the first metric whose key ends with the requested suffix."""
+ for key, value in metrics.items():
+ if key.endswith(needle):
+ return _safe_float(value)
+ return None
+
+
+def _event_depth(event_text: str) -> int:
+ """Compute indentation depth for an event row."""
+ return len(event_text) - len(event_text.lstrip(" "))
+
+
+def _make_highlights(
+ frame_time_ms: float | None,
+ metrics: dict[str, float | int | None],
+ top_events: list[dict[str, Any]],
+) -> list[str]:
+ """Generate short heuristic findings."""
+ highlights: list[str] = []
+
+ if frame_time_ms is not None:
+ if frame_time_ms > 33.3:
+ highlights.append("GPU frame is slower than 30 FPS budget.")
+ elif frame_time_ms > 16.7:
+ highlights.append("GPU frame exceeds 60 FPS budget.")
+
+ draw_count = metrics.get("draw_count")
+ dispatch_count = metrics.get("dispatch_count")
+ if isinstance(draw_count, int) and isinstance(dispatch_count, int):
+ if dispatch_count > max(draw_count * 2, 500):
+ highlights.append("Frame is compute-heavy relative to draw count.")
+
+ compute_sync = metrics.get("compute_queue_sync_active_pct")
+ if isinstance(compute_sync, float) and compute_sync > 50.0:
+ highlights.append("Synchronous compute queue activity is high.")
+
+ dram_pct = metrics.get("dram_throughput_pct")
+ if isinstance(dram_pct, float) and dram_pct > 60.0:
+ highlights.append("DRAM throughput is high enough to suggest memory pressure.")
+
+ if top_events:
+ top = top_events[0]
+ if frame_time_ms and top["time_ms"] >= frame_time_ms * 0.25:
+ highlights.append(f"Largest GPU event is '{top['event']}' at {top['time_ms']:.3f} ms.")
+
+ return highlights
+
+
+def summarize_export_dir(output_dir: str, top_n: int = 10) -> dict[str, Any]:
+ """Summarize exported GPU Trace tables from an output directory."""
+ output_root = str(Path(output_dir).resolve())
+ frame_path = _find_first(output_root, "FRAME.xls")
+ trace_frame_path = _find_first(output_root, "GPUTRACE_FRAME.xls")
+ events_path = _find_first(output_root, "D3DPERF_EVENTS.xls")
+ regimes_path = _find_first(output_root, "GPUTRACE_REGIMES.xls")
+
+ if not frame_path or not trace_frame_path or not events_path:
+ missing = [
+ name
+ for name, path in {
+ "FRAME.xls": frame_path,
+ "GPUTRACE_FRAME.xls": trace_frame_path,
+ "D3DPERF_EVENTS.xls": events_path,
+ }.items()
+ if not path
+ ]
+ raise RuntimeError(
+ "GPU Trace export summary requires exported tables. Missing: "
+ + ", ".join(missing)
+ )
+
+ frame_data = _read_kv_file(frame_path)
+ trace_metrics = _read_kv_file(trace_frame_path)
+ event_rows = _read_event_rows(events_path)
+
+ frame_time_ms = _safe_float(frame_data.get("GPU frame time"))
+ fps_estimate = (1000.0 / frame_time_ms) if frame_time_ms and frame_time_ms > 0 else None
+
+ summary_metrics: dict[str, float | int | None] = {}
+ for name, needle in SUMMARY_METRICS.items():
+ value = _pick_metric(trace_metrics, needle)
+ if name in {"draw_count", "dispatch_count"}:
+ summary_metrics[name] = _safe_int(value)
+ else:
+ summary_metrics[name] = value
+
+ ranked_events: list[dict[str, Any]] = []
+ for row in event_rows:
+ event_name = row["event_text"]
+ if event_name.startswith("Frame "):
+ continue
+ time_ms = _safe_float(row["time_ms"])
+ if time_ms is None or time_ms <= 0:
+ continue
+ ranked_events.append(
+ {
+ "event": event_name.strip(),
+ "time_ms": time_ms,
+ "depth": _event_depth(event_name),
+ }
+ )
+
+ ranked_events.sort(key=lambda item: item["time_ms"], reverse=True)
+ top_events = ranked_events[:top_n]
+ top_level_events = [item for item in top_events if item["depth"] == 0]
+
+ return {
+ "output_dir": output_root,
+ "files": {
+ "frame": frame_path,
+ "trace_frame": trace_frame_path,
+ "events": events_path,
+ "regimes": regimes_path,
+ },
+ "frame_time_ms": frame_time_ms,
+ "fps_estimate": fps_estimate,
+ "metrics": summary_metrics,
+ "top_events": top_events,
+ "top_level_events": top_level_events,
+ "highlights": _make_highlights(frame_time_ms, summary_metrics, top_events),
+ }
+
def capture_trace(
*,
@@ -30,6 +219,8 @@ def capture_trace(
metric_set_id: str | None,
multi_pass_metrics: bool,
real_time_shader_profiler: bool,
+ summarize: bool = False,
+ summary_limit: int = 10,
) -> dict:
"""Run a GPU Trace capture."""
report = backend.probe_installation(nsight_path=nsight_path)
@@ -55,6 +246,10 @@ def capture_trace(
)
if metric_set_id and not architecture:
raise ValueError("--metric-set-id requires --architecture.")
+ if summary_limit < 1:
+ raise ValueError("--summary-limit must be at least 1.")
+
+ auto_export = auto_export or summarize
extra_args: list[str] = []
if start_after_frames is not None:
@@ -104,4 +299,8 @@ def capture_trace(
result["tool_mode"] = "unified"
result["activity"] = "GPU Trace Profiler"
result["output_dir"] = output_dir or backend.default_output_dir()
+ result["auto_export"] = auto_export
+
+ if summarize:
+ result["summary"] = summarize_export_dir(result["output_dir"], top_n=summary_limit)
return result
diff --git a/nsight-graphics/agent-harness/cli_anything/nsight_graphics/nsight_graphics_cli.py b/nsight-graphics/agent-harness/cli_anything/nsight_graphics/nsight_graphics_cli.py
index 127d38e1e..cb832e395 100644
--- a/nsight-graphics/agent-harness/cli_anything/nsight_graphics/nsight_graphics_cli.py
+++ b/nsight-graphics/agent-harness/cli_anything/nsight_graphics/nsight_graphics_cli.py
@@ -49,6 +49,48 @@ def _common_kwargs(ctx: click.Context) -> dict:
}
+def _print_gpu_trace_summary(summary: dict) -> None:
+ """Render a compact human-readable GPU Trace summary."""
+ frame_time = summary.get("frame_time_ms")
+ fps = summary.get("fps_estimate")
+ if frame_time is not None:
+ click.echo(f"Frame time: {frame_time:.3f} ms")
+ if fps is not None:
+ click.echo(f"Estimated FPS: {fps:.2f}")
+
+ metrics = summary.get("metrics", {})
+ if metrics:
+ click.echo("Metrics:")
+ for label, key in [
+ ("Draws", "draw_count"),
+ ("Dispatches", "dispatch_count"),
+ ("Graphics active %", "graphics_engine_active_pct"),
+ ("Compute sync active %", "compute_queue_sync_active_pct"),
+ ("SM throughput %", "sm_throughput_pct"),
+ ("L2 throughput %", "l2_throughput_pct"),
+ ("DRAM throughput %", "dram_throughput_pct"),
+ ]:
+ value = metrics.get(key)
+ if value is None:
+ continue
+ if isinstance(value, float):
+ click.echo(f" {label}: {value:.3f}")
+ else:
+ click.echo(f" {label}: {value}")
+
+ top_events = summary.get("top_events", [])
+ if top_events:
+ click.echo("Top GPU events:")
+ for item in top_events:
+ click.echo(f" - {item['event']}: {item['time_ms']:.3f} ms")
+
+ highlights = summary.get("highlights", [])
+ if highlights:
+ click.echo("Highlights:")
+ for line in highlights:
+ click.echo(f" - {line}")
+
+
@click.group(invoke_without_command=True)
@click.option("--json", "json_mode", is_flag=True, help="Output in JSON format.")
@click.option("--debug", is_flag=True, help="Show debug tracebacks on errors.")
@@ -253,6 +295,8 @@ def gpu_trace_group():
@click.option("--metric-set-id", default=None, help="Metric set id for the selected architecture.")
@click.option("--multi-pass-metrics", is_flag=True, help="Enable multi-pass metrics.")
@click.option("--real-time-shader-profiler", is_flag=True, help="Enable real-time shader profiler.")
[email protected]("--summarize", is_flag=True, help="Parse exported GPU Trace tables and include a summary.")
[email protected]("--summary-limit", type=int, default=10, show_default=True, help="Number of top GPU events to include in the summary.")
@click.pass_context
def gpu_trace_capture_cmd(
ctx,
@@ -272,6 +316,8 @@ def gpu_trace_capture_cmd(
metric_set_id,
multi_pass_metrics,
real_time_shader_profiler,
+ summarize,
+ summary_limit,
):
"""Run a GPU Trace capture."""
try:
@@ -292,9 +338,32 @@ def gpu_trace_capture_cmd(
metric_set_id=metric_set_id,
multi_pass_metrics=multi_pass_metrics,
real_time_shader_profiler=real_time_shader_profiler,
+ summarize=summarize,
+ summary_limit=summary_limit,
**_common_kwargs(ctx),
)
- _output(ctx, data)
+ _output(
+ ctx,
+ data,
+ lambda payload: (
+ click.echo(f"Output dir: {payload.get('output_dir')}"),
+ click.echo(f"Artifacts: {payload.get('artifact_count', 0)}"),
+ _print_gpu_trace_summary(payload["summary"]) if payload.get("summary") else None,
+ ),
+ )
+ except Exception as exc:
+ _handle_exc(ctx, exc)
+
+
+@gpu_trace_group.command("summarize")
[email protected]("--input-dir", required=True, type=click.Path(exists=True, file_okay=False), help="GPU Trace export directory to summarize.")
[email protected]("--summary-limit", type=int, default=10, show_default=True, help="Number of top GPU events to include in the summary.")
+def gpu_trace_summarize_cmd(ctx, input_dir, summary_limit):
+ """Summarize an existing exported GPU Trace directory."""
+ try:
+ data = gpu_trace.summarize_export_dir(input_dir, top_n=summary_limit)
+ _output(ctx, data, _print_gpu_trace_summary)
except Exception as exc:
_handle_exc(ctx, exc)
@@ -346,7 +415,7 @@ def repl(ctx):
"doctor": "info|versions",
"launch": "detached|attach",
"frame": "capture",
- "gpu-trace": "capture",
+ "gpu-trace": "capture|summarize",
"cpp": "capture",
"help": "Show this help",
"quit": "Exit REPL",
diff --git a/nsight-graphics/agent-harness/cli_anything/nsight_graphics/skills/SKILL.md b/nsight-graphics/agent-harness/cli_anything/nsight_graphics/skills/SKILL.md
index 6fbb3c0de..2b52ceda0 100644
--- a/nsight-graphics/agent-harness/cli_anything/nsight_graphics/skills/SKILL.md
+++ b/nsight-graphics/agent-harness/cli_anything/nsight_graphics/skills/SKILL.md
@@ -24,7 +24,7 @@ Command-line orchestration of official NVIDIA Nsight Graphics activities.
- Launch an application detached under Nsight
- Attach Nsight to a running PID
- Trigger Frame Debugger capture
-- Trigger GPU Trace capture and auto-export
+- Trigger GPU Trace capture, auto-export, and summarize
- Trigger Generate C++ Capture
## Commands
@@ -59,7 +59,11 @@ cli-anything-nsight-graphics --output-dir D:\traces gpu-trace capture ^
--exe "C:\Path\To\App.exe" ^
--start-after-ms 1000 ^
--limit-to-frames 1 ^
- --auto-export
+ --auto-export ^
+ --summarize
+
+cli-anything-nsight-graphics gpu-trace summarize ^
+ --input-dir D:\traces
```
### Generate C++ Capture
@@ -76,6 +80,7 @@ cli-anything-nsight-graphics --output-dir D:\cpp cpp capture ^
- Use `doctor versions` to list detected installs when multiple Nsight Graphics versions exist.
- Use `--nsight-path` to force a specific install directory or `ngfx.exe`.
- Use `--json` for programmatic workflows.
+- Prefer `gpu-trace capture --auto-export --summarize` for one-step performance triage.
- Frame/GPU/C++ capture commands require a launch target through `--exe` or a
preconfigured root-level `--project`.
- V1 is orchestration-focused; it does not expose shader, pipeline, or resource
diff --git a/nsight-graphics/agent-harness/cli_anything/nsight_graphics/tests/TEST.md b/nsight-graphics/agent-harness/cli_anything/nsight_graphics/tests/TEST.md
index 31677e193..85c318637 100644
--- a/nsight-graphics/agent-harness/cli_anything/nsight_graphics/tests/TEST.md
+++ b/nsight-graphics/agent-harness/cli_anything/nsight_graphics/tests/TEST.md
@@ -2,7 +2,7 @@
## Test Inventory Plan
-- `test_core.py`: 28 unit tests planned
+- `test_core.py`: 31 unit tests planned
- `test_full_e2e.py`: 4 E2E tests planned
## Unit Test Plan
@@ -18,12 +18,14 @@
- fixed-drive discovery for non-`C:` installs
- unified and split command construction
- artifact diffing behavior
+- exported GPU Trace summary parsing
### `core/*.py`
- frame capture command routing
- split-mode fallback restrictions
- GPU Trace validation for trigger/limit options
+- GPU Trace one-step summary behavior
- launch attach/detached wrapping
### `nsight_graphics_cli.py`
@@ -62,8 +64,8 @@ python -m pytest cli_anything/nsight_graphics/tests -v --tb=no
============================= test session starts =============================
platform win32 -- Python 3.11.9, pytest-9.0.3, pluggy-1.6.0 -- C:\Users\aimidi\AppData\Local\Programs\Python\Python311\python.exe
cachedir: .pytest_cache
-rootdir: D:\code\D5\CLI-Anything-nsight-graphics\nsight-graphics\agent-harness
-collecting ... collected 32 items
+rootdir: D:\code\D5\CLI-Anything-nsight-graphics-dev\nsight-graphics\agent-harness
+collecting ... collected 35 items
cli_anything/nsight_graphics/tests/test_core.py::TestOutputAndErrors::test_output_json PASSED
cli_anything/nsight_graphics/tests/test_core.py::TestOutputAndErrors::test_handle_error_debug PASSED
@@ -79,11 +81,13 @@ cli_anything/nsight_graphics/tests/test_core.py::TestHelpParsing::test_parse_uni
cli_anything/nsight_graphics/tests/test_core.py::TestCommandBuilders::test_build_unified_command_formats_args_and_env PASSED
cli_anything/nsight_graphics/tests/test_core.py::TestCommandBuilders::test_build_split_capture_command_maps_wait_seconds PASSED
cli_anything/nsight_graphics/tests/test_core.py::TestCommandBuilders::test_diff_snapshots_reports_new_nonempty_files PASSED
+cli_anything/nsight_graphics/tests/test_core.py::TestCommandBuilders::test_gpu_trace_summary_from_export_dir PASSED
cli_anything/nsight_graphics/tests/test_core.py::TestCoreModules::test_frame_capture_uses_unified_ngfx PASSED
cli_anything/nsight_graphics/tests/test_core.py::TestCoreModules::test_frame_capture_split_mode_rejects_perf_exports PASSED
cli_anything/nsight_graphics/tests/test_core.py::TestCoreModules::test_gpu_trace_requires_arch_for_metric_set PASSED
cli_anything/nsight_graphics/tests/test_core.py::TestCoreModules::test_launch_attach_returns_unified_result PASSED
cli_anything/nsight_graphics/tests/test_core.py::TestCoreModules::test_cpp_capture_sets_activity PASSED
+cli_anything/nsight_graphics/tests/test_core.py::TestCoreModules::test_gpu_trace_capture_with_summary PASSED
cli_anything/nsight_graphics/tests/test_core.py::TestCLIHelp::test_root_help PASSED
cli_anything/nsight_graphics/tests/test_core.py::TestCLIHelp::test_nsight_path_is_forwarded_to_doctor PASSED
cli_anything/nsight_graphics/tests/test_core.py::TestCLIHelp::test_group_help[args0-info] PASSED
@@ -91,20 +95,21 @@ cli_anything/nsight_graphics/tests/test_core.py::TestCLIHelp::test_group_help[ar
cli_anything/nsight_graphics/tests/test_core.py::TestCLIHelp::test_group_help[args2-detached] PASSED
cli_anything/nsight_graphics/tests/test_core.py::TestCLIHelp::test_group_help[args3-capture] PASSED
cli_anything/nsight_graphics/tests/test_core.py::TestCLIHelp::test_group_help[args4-capture] PASSED
-cli_anything/nsight_graphics/tests/test_core.py::TestCLIHelp::test_group_help[args5-capture] PASSED
+cli_anything/nsight_graphics/tests/test_core.py::TestCLIHelp::test_group_help[args5-summarize] PASSED
+cli_anything/nsight_graphics/tests/test_core.py::TestCLIHelp::test_group_help[args6-capture] PASSED
cli_anything/nsight_graphics/tests/test_core.py::TestCLISubprocess::test_cli_help_subprocess PASSED
cli_anything/nsight_graphics/tests/test_full_e2e.py::TestDoctorE2E::test_doctor_info PASSED
cli_anything/nsight_graphics/tests/test_full_e2e.py::TestTargetedE2E::test_frame_capture SKIPPED
cli_anything/nsight_graphics/tests/test_full_e2e.py::TestTargetedE2E::test_gpu_trace_capture SKIPPED
cli_anything/nsight_graphics/tests/test_full_e2e.py::TestTargetedE2E::test_cpp_capture SKIPPED
-======================== 29 passed, 3 skipped in 1.83s ========================
+======================== 32 passed, 3 skipped in 1.92s ========================
```
## Summary Statistics
-- Total tests collected: 32
-- Passed: 29
+- Total tests collected: 35
+- Passed: 32
- Skipped: 3
- Pass rate for executed tests: 100%
diff --git a/nsight-graphics/agent-harness/cli_anything/nsight_graphics/tests/test_core.py b/nsight-graphics/agent-harness/cli_anything/nsight_graphics/tests/test_core.py
index c3c21f2c1..1a33a6ea4 100644
--- a/nsight-graphics/agent-harness/cli_anything/nsight_graphics/tests/test_core.py
+++ b/nsight-graphics/agent-harness/cli_anything/nsight_graphics/tests/test_core.py
@@ -286,6 +286,42 @@ class TestCommandBuilders:
assert diff[0]["path"].endswith("capture.ngfx-capture")
assert diff[0]["size"] > 0
+ def test_gpu_trace_summary_from_export_dir(self, tmp_path):
+ base = tmp_path / "BASE"
+ base.mkdir()
+ (base / "FRAME.xls").write_text("GPU frame time\t31.0446\n", encoding="utf-8")
+ (base / "GPUTRACE_FRAME.xls").write_text(
+ "\n".join(
+ [
+ "FE_B.TriageAC.fe__draw_count.sum\t309",
+ "FE_A.TriageAC.gr__dispatch_count.sum\t2561",
+ "FE_B.TriageAC.gr__cycles_active.avg.pct_of_peak_sustained_elapsed\t98.1079",
+ "FE_A.TriageAC.gr__compute_cycles_active_queue_sync.avg.pct_of_peak_sustained_elapsed\t84.24",
+ "TriageAC.sm__throughput.avg.pct_of_peak_sustained_elapsed\t23.6331",
+ "LTS.TriageAC.lts__throughput.avg.pct_of_peak_sustained_elapsed\t32.0437",
+ "FBSP.TriageAC.dramc__throughput.avg.pct_of_peak_sustained_elapsed\t19.5897",
+ ]
+ ),
+ encoding="utf-8",
+ )
+ (base / "D3DPERF_EVENTS.xls").write_text(
+ "event_text\ttime_ms\n"
+ "Frame 1221\t31.0431\n"
+ "Scene\t29.9644\n"
+ " DirectLighting\t15.3828\n"
+ " ReSTIRDI\t14.0627\n",
+ encoding="utf-8",
+ )
+
+ summary = gpu_trace.summarize_export_dir(str(tmp_path), top_n=3)
+ assert summary["frame_time_ms"] == pytest.approx(31.0446)
+ assert summary["fps_estimate"] == pytest.approx(1000.0 / 31.0446)
+ assert summary["metrics"]["draw_count"] == 309
+ assert summary["metrics"]["dispatch_count"] == 2561
+ assert summary["top_events"][0]["event"] == "Scene"
+ assert summary["top_events"][1]["event"] == "DirectLighting"
+ assert summary["highlights"]
+
class TestCoreModules:
@patch("cli_anything.nsight_graphics.core.frame.backend.run_with_artifacts")
@@ -440,6 +476,66 @@ class TestCoreModules:
assert result["activity"] == "Generate C++ Capture"
assert result["tool_mode"] == "unified"
+ @patch("cli_anything.nsight_graphics.core.gpu_trace.backend.run_with_artifacts")
+ @patch("cli_anything.nsight_graphics.core.gpu_trace.backend.build_unified_command")
+ @patch("cli_anything.nsight_graphics.core.gpu_trace.backend.probe_installation")
+ def test_gpu_trace_capture_with_summary(self, probe_mock, build_mock, run_mock, tmp_path):
+ base = tmp_path / "BASE"
+ base.mkdir()
+ (base / "FRAME.xls").write_text("GPU frame time\t16.0\n", encoding="utf-8")
+ (base / "GPUTRACE_FRAME.xls").write_text(
+ "FE_B.TriageAC.fe__draw_count.sum\t100\nFE_A.TriageAC.gr__dispatch_count.sum\t50\n",
+ encoding="utf-8",
+ )
+ (base / "D3DPERF_EVENTS.xls").write_text(
+ "event_text\ttime_ms\nFrame 1\t16.0\nScene\t10.0\n",
+ encoding="utf-8",
+ )
+
+ probe_mock.return_value = {
+ "binaries": {"ngfx": "C:/Nsight/ngfx.exe", "ngfx_capture": None, "ngfx_replay": None},
+ }
+ build_mock.return_value = ["C:/Nsight/ngfx.exe", "--activity", "GPU Trace Profiler"]
+ run_mock.return_value = {
+ "ok": True,
+ "returncode": 0,
+ "stdout": "",
+ "stderr": "",
+ "command": "ngfx",
+ "artifacts": [],
+ "artifact_count": 0,
+ }
+
+ result = gpu_trace.capture_trace(
+ nsight_path=None,
+ project=None,
+ output_dir=str(tmp_path),
+ hostname=None,
+ platform_name=None,
+ exe="C:/demo.exe",
+ working_dir=None,
+ args=(),
+ envs=(),
+ start_after_frames=1,
+ start_after_submits=None,
+ start_after_ms=None,
+ start_after_hotkey=False,
+ max_duration_ms=None,
+ limit_to_frames=1,
+ limit_to_submits=None,
+ auto_export=False,
+ architecture=None,
+ metric_set_id=None,
+ multi_pass_metrics=False,
+ real_time_shader_profiler=False,
+ summarize=True,
+ summary_limit=5,
+ )
+
+ assert result["auto_export"] is True
+ assert result["summary"]["frame_time_ms"] == pytest.approx(16.0)
+ assert result["summary"]["top_events"][0]["event"] == "Scene"
+
class TestCLIHelp:
def test_root_help(self):
@@ -478,6 +574,7 @@ class TestCLIHelp:
(["launch", "--help"], "detached"),
(["frame", "--help"], "capture"),
(["gpu-trace", "--help"], "capture"),
+ (["gpu-trace", "--help"], "summarize"),
(["cpp", "--help"], "capture"),
],
)
diff --git a/registry.json b/registry.json
index 977253810..54f521b76 100644
--- a/registry.json
+++ b/registry.json
@@ -657,9 +657,9 @@
},
{
"name": "nsight-graphics",
- "display_name": "Nsight Graphics",
+ "display_name": "Nsight Graphics CLI",
"version": "0.1.0",
- "description": "Windows-first orchestration of Nsight Graphics launch, Frame Debugger capture, GPU Trace, and Generate C++ Capture",
+ "description": "Windows-first Nsight Graphics CLI for Graphics/Frame capture, GPU Trace, Generate C++ Capture, and one-step GPU Trace summary",
"requires": "NVIDIA Nsight Graphics installation with ngfx.exe or newer split capture/replay tools",
"homepage": "https://developer.nvidia.com/nsight-graphics",
"install_cmd": "pip install git+https://github.com/HKUDS/CLI-Anything.git#subdirectory=nsight-graphics/agent-harness",