Skip to content

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

Python

refactor: split nsight graphics backend helpers

aimidid7553287be2a
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 950fb1253..d616c10b1 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
@@ -78,7 +78,7 @@ class TestOutputAndErrors:
class TestBackendDiscovery:
def test_default_windows_install_dirs_prefers_higher_version(self):
- with patch("cli_anything.nsight_graphics.utils.nsight_graphics_backend._fixed_windows_drive_roots", return_value=["C:", "D:"]):
+ with patch("cli_anything.nsight_graphics.utils.backend.discovery._fixed_windows_drive_roots", return_value=["C:", "D:"]):
result = backend._default_windows_install_dirs(
lambda pattern: {
"C:/Program Files/NVIDIA Corporation/Nsight Graphics */host/windows-desktop-nomad-x64": [
@@ -132,7 +132,7 @@ class TestBackendDiscovery:
(install_dir / "ngfx.exe").write_text("", encoding="utf-8")
(install_dir / "ngfx-ui.exe").write_text("", encoding="utf-8")
- with patch("cli_anything.nsight_graphics.utils.nsight_graphics_backend._read_registry_installations", return_value=[]):
+ with patch("cli_anything.nsight_graphics.utils.backend.discovery._read_registry_installations", return_value=[]):
result = backend.list_installations(
env={},
nsight_path=str(install_dir),
@@ -157,7 +157,7 @@ class TestBackendDiscovery:
"registry_key": r"HKLM\SOFTWARE\...\{ABC}",
}
]
- with patch("cli_anything.nsight_graphics.utils.nsight_graphics_backend._read_registry_installations", return_value=registry_entries):
+ with patch("cli_anything.nsight_graphics.utils.backend.discovery._read_registry_installations", return_value=registry_entries):
result = backend.list_installations(
env={},
which=lambda _: None,
@@ -188,7 +188,7 @@ class TestBackendDiscovery:
"registry_key": r"HKLM\SOFTWARE\...\{DEF}",
}
]
- with patch("cli_anything.nsight_graphics.utils.nsight_graphics_backend._read_registry_installations", return_value=registry_entries):
+ with patch("cli_anything.nsight_graphics.utils.backend.discovery._read_registry_installations", return_value=registry_entries):
result = backend.list_installations(
env={},
nsight_path=str(install_dir),
@@ -211,8 +211,8 @@ class TestBackendDiscovery:
(c_dir / "ngfx.exe").write_text("", encoding="utf-8")
(d_dir / "ngfx.exe").write_text("", encoding="utf-8")
- with patch("cli_anything.nsight_graphics.utils.nsight_graphics_backend._fixed_windows_drive_roots", return_value=["C:", "D:"]), \
- patch("cli_anything.nsight_graphics.utils.nsight_graphics_backend._read_registry_installations", return_value=[]):
+ with patch("cli_anything.nsight_graphics.utils.backend.discovery._fixed_windows_drive_roots", return_value=["C:", "D:"]), \
+ patch("cli_anything.nsight_graphics.utils.backend.discovery._read_registry_installations", return_value=[]):
result = backend.list_installations(
env={},
which=lambda _: None,
@@ -288,7 +288,7 @@ class TestCommandBuilders:
assert "--capture-countdown-timer" in command
assert command[command.index("--capture-countdown-timer") + 1] == "3000"
- @patch("cli_anything.nsight_graphics.utils.nsight_graphics_backend.subprocess.run")
+ @patch("cli_anything.nsight_graphics.utils.backend.execution.subprocess.run")
def test_run_command_suppresses_graphics_capture_suggestion_dialog(self, run_mock):
run_mock.return_value = type("Result", (), {"returncode": 0, "stdout": "", "stderr": ""})()
backend.run_command(["C:/Nsight/ngfx.exe", "--help"])
diff --git a/nsight-graphics/agent-harness/cli_anything/nsight_graphics/utils/backend/__init__.py b/nsight-graphics/agent-harness/cli_anything/nsight_graphics/utils/backend/__init__.py
new file mode 100644
index 000000000..eb5aca07b
--- /dev/null
+++ b/nsight-graphics/agent-harness/cli_anything/nsight_graphics/utils/backend/__init__.py
@@ -0,0 +1 @@
+"""Focused backend helpers for cli-anything-nsight-graphics."""
diff --git a/nsight-graphics/agent-harness/cli_anything/nsight_graphics/utils/backend/commands.py b/nsight-graphics/agent-harness/cli_anything/nsight_graphics/utils/backend/commands.py
new file mode 100644
index 000000000..cdea16813
--- /dev/null
+++ b/nsight-graphics/agent-harness/cli_anything/nsight_graphics/utils/backend/commands.py
@@ -0,0 +1,150 @@
+"""Validation and command-building helpers for Nsight CLI invocations."""
+
+from __future__ import annotations
+
+import subprocess
+from typing import Optional, Sequence
+
+from cli_anything.nsight_graphics.utils.backend.discovery import INSTALL_INSTRUCTIONS
+
+
+def require_binary(binaries: dict[str, Optional[str]], key: str) -> str:
+ """Require a specific executable to exist."""
+ path = binaries.get(key)
+ if not path:
+ raise RuntimeError(INSTALL_INSTRUCTIONS)
+ return path
+
+
+def require_launch_target(*, project: Optional[str], exe: Optional[str]) -> None:
+ """Require at least one launch target input."""
+ if not project and not exe:
+ raise ValueError("Specify --exe or set --project at the root level.")
+
+
+def ensure_exactly_one(label: str, flags: dict[str, bool]) -> str:
+ """Validate that exactly one flag in the set is selected."""
+ selected = [name for name, enabled in flags.items() if enabled]
+ if len(selected) != 1:
+ choices = ", ".join(flags.keys())
+ raise ValueError(f"{label}: choose exactly one of {choices}.")
+ return selected[0]
+
+
+def ensure_at_most_one(label: str, flags: dict[str, bool]) -> Optional[str]:
+ """Validate that zero or one flags are selected."""
+ selected = [name for name, enabled in flags.items() if enabled]
+ if len(selected) > 1:
+ choices = ", ".join(flags.keys())
+ raise ValueError(f"{label}: choose at most one of {choices}.")
+ return selected[0] if selected else None
+
+
+def format_env_values(envs: Sequence[str]) -> Optional[str]:
+ """Format KEY=VALUE entries for ngfx.exe."""
+ cleaned = [entry.strip() for entry in envs if entry and entry.strip()]
+ if not cleaned:
+ return None
+ joined = "; ".join(cleaned)
+ if not joined.endswith(";"):
+ joined += ";"
+ return joined
+
+
+def format_program_args(args: Sequence[str]) -> Optional[str]:
+ """Format target executable arguments."""
+ cleaned = [entry for entry in args if entry]
+ if not cleaned:
+ return None
+ return subprocess.list2cmdline(cleaned)
+
+
+def build_unified_command(
+ binaries: dict[str, Optional[str]],
+ *,
+ activity: Optional[str] = None,
+ project: Optional[str] = None,
+ output_dir: Optional[str] = None,
+ hostname: Optional[str] = None,
+ platform_name: Optional[str] = None,
+ exe: Optional[str] = None,
+ working_dir: Optional[str] = None,
+ args: Sequence[str] = (),
+ envs: Sequence[str] = (),
+ attach_pid: Optional[int] = None,
+ launch_detached: bool = False,
+ extra_args: Sequence[str] = (),
+) -> list[str]:
+ """Build a command line for the unified ngfx.exe CLI."""
+ ngfx = require_binary(binaries, "ngfx")
+ command: list[str] = [ngfx]
+ if hostname:
+ command.extend(["--hostname", hostname])
+ if project:
+ command.extend(["--project", project])
+ if output_dir:
+ command.extend(["--output-dir", output_dir])
+ if activity:
+ command.extend(["--activity", activity])
+ if platform_name:
+ command.extend(["--platform", platform_name])
+ if launch_detached:
+ command.append("--launch-detached")
+ if attach_pid is not None:
+ command.extend(["--attach-pid", str(attach_pid)])
+ if exe:
+ command.extend(["--exe", exe])
+ if working_dir:
+ command.extend(["--dir", working_dir])
+ formatted_args = format_program_args(args)
+ if formatted_args:
+ command.extend(["--args", formatted_args])
+ formatted_env = format_env_values(envs)
+ if formatted_env:
+ command.extend(["--env", formatted_env])
+ command.extend(extra_args)
+ return command
+
+
+def build_split_capture_command(
+ binaries: dict[str, Optional[str]],
+ *,
+ exe: str,
+ output_dir: Optional[str] = None,
+ working_dir: Optional[str] = None,
+ args: Sequence[str] = (),
+ envs: Sequence[str] = (),
+ wait_seconds: Optional[int] = None,
+ wait_frames: Optional[int] = None,
+ wait_hotkey: bool = False,
+ frame_count: int = 1,
+) -> list[str]:
+ """Build a command line for the split ngfx-capture tool."""
+ capture = require_binary(binaries, "ngfx_capture")
+ command: list[str] = [capture, "--exe", exe, "--frame-count", str(frame_count)]
+ if output_dir:
+ command.extend(["--output-dir", output_dir])
+ if working_dir:
+ command.extend(["--working-dir", working_dir])
+ formatted_args = format_program_args(args)
+ if formatted_args:
+ command.extend(["--args", formatted_args])
+ formatted_env = format_env_values(envs)
+ if formatted_env:
+ command.extend(["--env", formatted_env])
+
+ ensure_exactly_one(
+ "frame trigger",
+ {
+ "wait_seconds": wait_seconds is not None,
+ "wait_frames": wait_frames is not None,
+ "wait_hotkey": wait_hotkey,
+ },
+ )
+ if wait_seconds is not None:
+ command.extend(["--capture-countdown-timer", str(wait_seconds * 1000)])
+ elif wait_frames is not None:
+ command.extend(["--capture-frame", str(wait_frames)])
+ else:
+ command.append("--capture-hotkey")
+ return command
diff --git a/nsight-graphics/agent-harness/cli_anything/nsight_graphics/utils/backend/discovery.py b/nsight-graphics/agent-harness/cli_anything/nsight_graphics/utils/backend/discovery.py
new file mode 100644
index 000000000..e1585351d
--- /dev/null
+++ b/nsight-graphics/agent-harness/cli_anything/nsight_graphics/utils/backend/discovery.py
@@ -0,0 +1,507 @@
+"""Discovery, registry, and probe helpers for Nsight Graphics."""
+
+from __future__ import annotations
+
+import ctypes
+import glob
+import os
+import platform
+import shutil
+from pathlib import Path
+from typing import Any, Callable, Optional
+
+from cli_anything.nsight_graphics.utils.backend.execution import _combined_output, run_command
+from cli_anything.nsight_graphics.utils.backend.parsing import parse_option_help, parse_unified_help
+from cli_anything.nsight_graphics.utils.backend.shared import (
+ _dedupe,
+ _extract_version_from_path,
+ _extract_version_from_text,
+ _version_sort_key,
+)
+
+ENV_VAR = "NSIGHT_GRAPHICS_PATH"
+
+_BINARY_CANDIDATES = {
+ "ngfx": ("ngfx.exe", "ngfx"),
+ "ngfx_ui": ("ngfx-ui.exe", "ngfx-ui"),
+ "ngfx_capture": ("ngfx-capture.exe", "ngfx-capture"),
+ "ngfx_replay": ("ngfx-replay.exe", "ngfx-replay"),
+}
+
+INSTALL_INSTRUCTIONS = (
+ "Nsight Graphics CLI tools were not found.\n"
+ "Install NVIDIA Nsight Graphics and make sure ngfx.exe is available, or set "
+ f"{ENV_VAR} to the install directory or executable path.\n"
+ "Typical Windows location:\n"
+ " C:\\Program Files\\NVIDIA Corporation\\Nsight Graphics <version>\\host\\windows-desktop-nomad-x64"
+)
+
+
+def _scan_directory(directory: str) -> dict[str, str]:
+ """Scan a directory for known Nsight binaries."""
+ found: dict[str, str] = {}
+ base = Path(directory)
+ if not base.is_dir():
+ return found
+ for key, candidates in _BINARY_CANDIDATES.items():
+ for candidate in candidates:
+ path = base / candidate
+ if path.is_file():
+ found[key] = str(path.resolve())
+ break
+ return found
+
+
+def _candidate_dirs_from_env(path_value: str) -> list[str]:
+ """Resolve environment override into candidate directories."""
+ if not path_value:
+ return []
+ path = Path(path_value)
+ candidates: list[str] = []
+ if path.is_file():
+ candidates.append(str(path.parent))
+ else:
+ candidates.append(str(path))
+ candidates.append(str(path / "host" / "windows-desktop-nomad-x64"))
+ candidates.append(str(path / "windows-desktop-nomad-x64"))
+ return _dedupe([p for p in candidates if Path(p).exists()])
+
+
+def _fixed_windows_drive_roots() -> list[str]:
+ """Return fixed-drive roots such as C: and D: on Windows."""
+ if platform.system() != "Windows":
+ return []
+ try:
+ drive_mask = ctypes.windll.kernel32.GetLogicalDrives()
+ get_drive_type = ctypes.windll.kernel32.GetDriveTypeW
+ except Exception:
+ return []
+
+ DRIVE_FIXED = 3
+ drives: list[str] = []
+ for index in range(26):
+ if not (drive_mask & (1 << index)):
+ continue
+ letter = chr(ord("A") + index)
+ root = f"{letter}:\\"
+ try:
+ if get_drive_type(root) == DRIVE_FIXED:
+ drives.append(f"{letter}:")
+ except Exception:
+ continue
+ return drives
+
+
+def _default_windows_install_dirs(
+ glob_func: Callable[[str], list[str]],
+) -> list[str]:
+ """Return default Windows install directories for Nsight Graphics."""
+ drive_roots = _fixed_windows_drive_roots()
+ if not drive_roots:
+ drive_roots = ["C:"]
+
+ patterns: list[str] = []
+ for drive in drive_roots:
+ patterns.extend(
+ [
+ f"{drive}/Program Files/NVIDIA Corporation/Nsight Graphics */host/windows-desktop-nomad-x64",
+ f"{drive}/Program Files (x86)/NVIDIA Corporation/Nsight Graphics */host/windows-desktop-nomad-x64",
+ ]
+ )
+ matches: list[str] = []
+ for pattern in patterns:
+ matches.extend(glob_func(pattern))
+ return _dedupe(
+ sorted(
+ matches,
+ key=lambda path: (_version_sort_key(_extract_version_from_path(path)), path),
+ reverse=True,
+ )
+ )
+
+
+def _read_registry_installations(
+ platform_system: Optional[str] = None,
+) -> list[dict[str, Any]]:
+ """Read Nsight Graphics install records from the Windows uninstall registry."""
+ platform_system = platform.system() if platform_system is None else platform_system
+ if platform_system != "Windows":
+ return []
+
+ try:
+ import winreg
+ except ImportError:
+ return []
+
+ uninstall_roots = [
+ (winreg.HKEY_LOCAL_MACHINE, r"SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall"),
+ (winreg.HKEY_LOCAL_MACHINE, r"SOFTWARE\WOW6432Node\Microsoft\Windows\CurrentVersion\Uninstall"),
+ ]
+
+ def _query_value(key, name: str) -> Optional[str]:
+ try:
+ value, _ = winreg.QueryValueEx(key, name)
+ except OSError:
+ return None
+ if value is None:
+ return None
+ text = str(value).strip()
+ return text or None
+
+ records: list[dict[str, Any]] = []
+ for hive, root in uninstall_roots:
+ try:
+ with winreg.OpenKey(hive, root) as root_key:
+ index = 0
+ while True:
+ try:
+ subkey_name = winreg.EnumKey(root_key, index)
+ except OSError:
+ break
+ index += 1
+ try:
+ with winreg.OpenKey(root_key, subkey_name) as subkey:
+ display_name = _query_value(subkey, "DisplayName")
+ if not display_name or "Nsight Graphics" not in display_name:
+ continue
+ records.append(
+ {
+ "display_name": display_name,
+ "display_version": _query_value(subkey, "DisplayVersion"),
+ "install_location": _query_value(subkey, "InstallLocation"),
+ "install_source": _query_value(subkey, "InstallSource"),
+ "uninstall_string": _query_value(subkey, "UninstallString"),
+ "publisher": _query_value(subkey, "Publisher"),
+ "registry_key": f"HKLM\\{root}\\{subkey_name}",
+ }
+ )
+ except OSError:
+ continue
+ except OSError:
+ continue
+ return records
+
+
+def _normalized_install_key(path: str) -> str:
+ """Normalize a path for install-root comparisons across slash styles."""
+ normalized = os.path.normcase(os.path.normpath(path))
+ return normalized.replace("\\", "/").rstrip("/")
+
+
+def _override_value(
+ env: dict[str, str],
+ nsight_path: Optional[str] = None,
+) -> str:
+ """Resolve the effective override path from CLI or environment."""
+ if nsight_path and nsight_path.strip():
+ return nsight_path.strip()
+ return env.get(ENV_VAR, "").strip()
+
+
+def detect_tool_mode(binaries: dict[str, Optional[str]]) -> str:
+ """Return compatibility mode for the discovered binaries."""
+ if binaries.get("ngfx_capture") or binaries.get("ngfx_replay"):
+ return "split"
+ if binaries.get("ngfx"):
+ return "unified"
+ return "missing"
+
+
+def discover_binaries(
+ env: Optional[dict[str, str]] = None,
+ which: Optional[Callable[[str], Optional[str]]] = None,
+ glob_func: Optional[Callable[[str], list[str]]] = None,
+ platform_system: Optional[str] = None,
+ nsight_path: Optional[str] = None,
+) -> dict[str, Any]:
+ """Discover available Nsight binaries."""
+ env = os.environ if env is None else env
+ which = shutil.which if which is None else which
+ glob_func = glob.glob if glob_func is None else glob_func
+ platform_system = platform.system() if platform_system is None else platform_system
+
+ binaries: dict[str, Optional[str]] = {
+ "ngfx": None,
+ "ngfx_ui": None,
+ "ngfx_capture": None,
+ "ngfx_replay": None,
+ }
+ search_roots: list[str] = []
+ override = _override_value(env, nsight_path=nsight_path)
+
+ if override:
+ override_path = Path(override)
+ if override_path.is_file():
+ for key, candidates in _BINARY_CANDIDATES.items():
+ lowered = {name.lower() for name in candidates}
+ if override_path.name.lower() in lowered:
+ binaries[key] = str(override_path.resolve())
+ break
+ search_roots.extend(_candidate_dirs_from_env(override))
+
+ for key, candidates in _BINARY_CANDIDATES.items():
+ for candidate in candidates:
+ resolved = which(candidate)
+ if resolved:
+ binaries[key] = binaries[key] or str(Path(resolved).resolve())
+ search_roots.append(str(Path(resolved).resolve().parent))
+ break
+
+ if platform_system == "Windows":
+ search_roots.extend(_default_windows_install_dirs(glob_func))
+
+ for directory in _dedupe(search_roots):
+ found = _scan_directory(directory)
+ for key, value in found.items():
+ binaries[key] = binaries[key] or value
+
+ return {
+ "binaries": binaries,
+ "search_roots": _dedupe(search_roots),
+ "env_override": env.get(ENV_VAR, "").strip() or None,
+ "cli_override": nsight_path.strip() if nsight_path and nsight_path.strip() else None,
+ "effective_override": override or None,
+ }
+
+
+def _primary_executable(binaries: dict[str, Optional[str]]) -> Optional[str]:
+ """Choose the preferred executable path to display."""
+ return binaries.get("ngfx") or binaries.get("ngfx_capture") or binaries.get("ngfx_replay")
+
+
+def list_installations(
+ env: Optional[dict[str, str]] = None,
+ which: Optional[Callable[[str], Optional[str]]] = None,
+ glob_func: Optional[Callable[[str], list[str]]] = None,
+ platform_system: Optional[str] = None,
+ nsight_path: Optional[str] = None,
+) -> dict[str, Any]:
+ """List installed Nsight Graphics directories and versions."""
+ env = os.environ if env is None else env
+ which = shutil.which if which is None else which
+ glob_func = glob.glob if glob_func is None else glob_func
+ platform_system = platform.system() if platform_system is None else platform_system
+
+ discovered = discover_binaries(
+ env=env,
+ which=which,
+ glob_func=glob_func,
+ platform_system=platform_system,
+ nsight_path=nsight_path,
+ )
+ selected_path = _primary_executable(discovered["binaries"])
+
+ candidates: list[str] = []
+ for root in discovered["search_roots"]:
+ candidates.append(root)
+ if platform_system == "Windows":
+ candidates.extend(_default_windows_install_dirs(glob_func))
+ if nsight_path:
+ candidates.extend(_candidate_dirs_from_env(nsight_path))
+ if env.get(ENV_VAR, "").strip():
+ candidates.extend(_candidate_dirs_from_env(env[ENV_VAR]))
+ for key, names in _BINARY_CANDIDATES.items():
+ for name in names:
+ resolved = which(name)
+ if resolved:
+ candidates.append(str(Path(resolved).resolve().parent))
+ break
+
+ installations: list[dict[str, Any]] = []
+ installation_keys: set[str] = set()
+ for directory in _dedupe(candidates):
+ found = _scan_directory(directory)
+ if not found:
+ continue
+ primary = _primary_executable(found)
+ key = f"fs::{os.path.normcase(os.path.normpath(directory))}"
+ installation_keys.add(key)
+ installations.append(
+ {
+ "install_root": directory,
+ "version": _extract_version_from_path(directory) or _extract_version_from_path(primary or ""),
+ "tool_mode": detect_tool_mode(found),
+ "selected": bool(
+ primary and selected_path and os.path.normcase(primary) == os.path.normcase(selected_path)
+ ),
+ "discovery_sources": ["filesystem"],
+ "registered_only": False,
+ "registry_key": None,
+ "display_name": None,
+ "display_version": None,
+ "install_source": None,
+ "binaries": {
+ binary_key: found.get(binary_key)
+ for binary_key in ("ngfx", "ngfx_ui", "ngfx_capture", "ngfx_replay")
+ },
+ }
+ )
+
+ for record in _read_registry_installations(platform_system=platform_system):
+ install_location = record.get("install_location")
+ normalized_location = None
+ if install_location:
+ normalized_location = _normalized_install_key(install_location)
+ guessed_version = (
+ _extract_version_from_text(record.get("display_name") or "")
+ or _extract_version_from_text(record.get("display_version") or "")
+ )
+
+ matched_entry = None
+ if normalized_location:
+ for item in installations:
+ item_root = item.get("install_root")
+ if not item_root:
+ continue
+ normalized_root = _normalized_install_key(item_root)
+ if (
+ normalized_root == normalized_location
+ or normalized_root.startswith(normalized_location + "/")
+ or normalized_location.startswith(normalized_root + "/")
+ ):
+ matched_entry = item
+ break
+ elif guessed_version:
+ same_version = [
+ item
+ for item in installations
+ if not item.get("registered_only") and item.get("version") == guessed_version
+ ]
+ if len(same_version) == 1:
+ matched_entry = same_version[0]
+
+ if matched_entry is not None:
+ matched_entry["discovery_sources"] = _dedupe(
+ list(matched_entry.get("discovery_sources", [])) + ["registry"]
+ )
+ matched_entry["display_name"] = record.get("display_name")
+ matched_entry["display_version"] = record.get("display_version")
+ matched_entry["registry_key"] = record.get("registry_key")
+ matched_entry["install_source"] = record.get("install_source")
+ if not matched_entry.get("version"):
+ matched_entry["version"] = guessed_version
+ continue
+
+ registry_key = f"reg::{record['registry_key']}"
+ if registry_key in installation_keys:
+ continue
+ installation_keys.add(registry_key)
+ installations.append(
+ {
+ "install_root": install_location or None,
+ "version": guessed_version,
+ "tool_mode": "registered-only",
+ "selected": False,
+ "discovery_sources": ["registry"],
+ "registered_only": True,
+ "registry_key": record.get("registry_key"),
+ "display_name": record.get("display_name"),
+ "display_version": record.get("display_version"),
+ "install_source": record.get("install_source"),
+ "binaries": {
+ "ngfx": None,
+ "ngfx_ui": None,
+ "ngfx_capture": None,
+ "ngfx_replay": None,
+ },
+ }
+ )
+
+ installations.sort(
+ key=lambda item: (
+ not item["selected"],
+ item.get("registered_only", False),
+ item.get("version") or "",
+ item.get("install_root") or item.get("display_name") or "",
+ ),
+ reverse=False,
+ )
+ return {
+ "ok": bool(installations),
+ "selected_executable": selected_path,
+ "count": len(installations),
+ "installations": installations,
+ "cli_override": discovered.get("cli_override"),
+ "env_override": discovered.get("env_override"),
+ "registry_count": sum(
+ 1 for item in installations if "registry" in item.get("discovery_sources", [])
+ ),
+ }
+
+
+def get_version(binaries: dict[str, Optional[str]]) -> Optional[str]:
+ """Best-effort version detection from CLI output or path."""
+ preferred = binaries.get("ngfx") or binaries.get("ngfx_capture") or binaries.get("ngfx_replay")
+ if not preferred:
+ return None
+ result = run_command([preferred, "--version"], timeout=10)
+ text = _combined_output(result)
+ return _extract_version_from_text(text) or _extract_version_from_path(preferred)
+
+
+def probe_installation(nsight_path: Optional[str] = None) -> dict[str, Any]:
+ """Return an installation and capability report."""
+ discovered = discover_binaries(nsight_path=nsight_path)
+ binaries = discovered["binaries"]
+ mode = detect_tool_mode(binaries)
+ version = get_version(binaries)
+
+ help_metadata = {
+ "activities": [],
+ "platforms": [],
+ "general_options": [],
+ "activity_options": {},
+ }
+ if binaries.get("ngfx"):
+ help_result = run_command([binaries["ngfx"], "--help-all"], timeout=15)
+ help_metadata.update(parse_unified_help(_combined_output(help_result)))
+
+ capture_options: list[str] = []
+ if binaries.get("ngfx_capture"):
+ capture_help = run_command([binaries["ngfx_capture"], "--help"], timeout=15)
+ capture_options = parse_option_help(_combined_output(capture_help))
+
+ replay_options: list[str] = []
+ if binaries.get("ngfx_replay"):
+ replay_help = run_command([binaries["ngfx_replay"], "--help"], timeout=15)
+ replay_options = parse_option_help(_combined_output(replay_help))
+
+ warnings: list[str] = []
+ host_platform = platform.system()
+ if host_platform != "Windows":
+ warnings.append(
+ "V1 is only verified on Windows-hosted Nsight Graphics installations."
+ )
+ if mode == "missing":
+ warnings.append(INSTALL_INSTRUCTIONS)
+ if mode == "split" and not binaries.get("ngfx"):
+ warnings.append(
+ "Split capture/replay tools were found without ngfx.exe; launch, attach, "
+ "GPU Trace, and C++ Capture helpers may be unavailable."
+ )
+
+ return {
+ "ok": _primary_executable(binaries) is not None,
+ "tool_mode": mode,
+ "compatibility_mode": mode,
+ "resolved_executable": _primary_executable(binaries),
+ "version": version,
+ "host_platform": host_platform,
+ "verified_host": host_platform == "Windows",
+ "supported_activities": help_metadata["activities"],
+ "supported_platforms": help_metadata["platforms"],
+ "general_options": help_metadata["general_options"],
+ "activity_options": help_metadata["activity_options"],
+ "split_binaries_present": {
+ "ngfx_capture": bool(binaries.get("ngfx_capture")),
+ "ngfx_replay": bool(binaries.get("ngfx_replay")),
+ },
+ "capture_options": capture_options,
+ "replay_options": replay_options,
+ "binaries": binaries,
+ "search_roots": discovered["search_roots"],
+ "env_override": discovered["env_override"],
+ "cli_override": discovered.get("cli_override"),
+ "effective_override": discovered.get("effective_override"),
+ "warnings": warnings,
+ }
diff --git a/nsight-graphics/agent-harness/cli_anything/nsight_graphics/utils/backend/execution.py b/nsight-graphics/agent-harness/cli_anything/nsight_graphics/utils/backend/execution.py
new file mode 100644
index 000000000..1bd6803f6
--- /dev/null
+++ b/nsight-graphics/agent-harness/cli_anything/nsight_graphics/utils/backend/execution.py
@@ -0,0 +1,140 @@
+"""Process execution and artifact tracking helpers."""
+
+from __future__ import annotations
+
+import os
+import subprocess
+from pathlib import Path
+from typing import Any, Optional, Sequence
+
+from cli_anything.nsight_graphics.utils.backend.shared import _command_string, _dedupe
+
+
+def _combined_output(result: dict[str, Any]) -> str:
+ """Combine stdout and stderr for downstream parsers."""
+ stdout = result.get("stdout", "") or ""
+ stderr = result.get("stderr", "") or ""
+ return "\n".join(part for part in (stdout, stderr) if part)
+
+
+def run_command(
+ args: Sequence[str],
+ *,
+ cwd: Optional[str] = None,
+ timeout: int = 120,
+) -> dict[str, Any]:
+ """Run a subprocess and normalize the result."""
+ try:
+ env = os.environ.copy()
+ env.setdefault("NSIGHT_SUGGEST_GRAPHICS_CAPTURE", "0")
+ proc = subprocess.run(
+ list(args),
+ capture_output=True,
+ text=True,
+ cwd=cwd,
+ timeout=timeout,
+ env=env,
+ )
+ return {
+ "ok": proc.returncode == 0,
+ "returncode": proc.returncode,
+ "stdout": proc.stdout.strip(),
+ "stderr": proc.stderr.strip(),
+ "command": _command_string(args),
+ }
+ except FileNotFoundError as exc:
+ return {
+ "ok": False,
+ "returncode": -1,
+ "stdout": "",
+ "stderr": str(exc),
+ "command": _command_string(args),
+ }
+ except subprocess.TimeoutExpired:
+ return {
+ "ok": False,
+ "returncode": -1,
+ "stdout": "",
+ "stderr": f"Command timed out after {timeout}s",
+ "command": _command_string(args),
+ }
+
+
+def default_output_dir() -> str:
+ """Best-effort default output root used by the harness."""
+ return str((Path.home() / "Documents" / "NVIDIA Nsight Graphics").resolve())
+
+
+def activity_artifact_roots(activity: str, output_dir: Optional[str]) -> list[str]:
+ """Return directories to scan for generated artifacts."""
+ base = Path(default_output_dir())
+ roots: list[str] = []
+ if output_dir:
+ roots.append(str(Path(output_dir).resolve()))
+ else:
+ roots.append(str(base))
+
+ normalized = activity.lower()
+ if normalized in {"frame debugger", "graphics capture"}:
+ roots.extend([str(base), str(base / "GraphicsCaptures")])
+ elif normalized == "gpu trace profiler":
+ if not output_dir:
+ roots.append(str(base / "GPUTrace"))
+ elif normalized == "generate c++ capture":
+ roots.append(str(base / "CppCaptures"))
+ return _dedupe(roots)
+
+
+def snapshot_files(roots: Sequence[str]) -> dict[str, tuple[int, int]]:
+ """Snapshot file mtimes and sizes under the supplied roots."""
+ snapshot: dict[str, tuple[int, int]] = {}
+ for root in roots:
+ root_path = Path(root)
+ if not root_path.is_dir():
+ continue
+ for path in root_path.rglob("*"):
+ if not path.is_file():
+ continue
+ try:
+ stat = path.stat()
+ except OSError:
+ continue
+ snapshot[str(path.resolve())] = (stat.st_mtime_ns, stat.st_size)
+ return snapshot
+
+
+def diff_snapshots(
+ before: dict[str, tuple[int, int]],
+ after: dict[str, tuple[int, int]],
+) -> list[dict[str, Any]]:
+ """Return non-empty files that were created or updated."""
+ artifacts: list[dict[str, Any]] = []
+ for path, (mtime_ns, size) in sorted(after.items()):
+ previous = before.get(path)
+ if size <= 0:
+ continue
+ if previous is None or previous != (mtime_ns, size):
+ artifacts.append(
+ {
+ "path": path,
+ "size": size,
+ "mtime_ns": mtime_ns,
+ }
+ )
+ return artifacts
+
+
+def run_with_artifacts(
+ args: Sequence[str],
+ *,
+ output_roots: Sequence[str],
+ cwd: Optional[str] = None,
+ timeout: int = 300,
+) -> dict[str, Any]:
+ """Run a command and discover artifacts under the supplied roots."""
+ before = snapshot_files(output_roots)
+ result = run_command(args, cwd=cwd, timeout=timeout)
+ after = snapshot_files(output_roots)
+ result["artifacts"] = diff_snapshots(before, after)
+ result["artifact_count"] = len(result["artifacts"])
+ return result
diff --git a/nsight-graphics/agent-harness/cli_anything/nsight_graphics/utils/backend/parsing.py b/nsight-graphics/agent-harness/cli_anything/nsight_graphics/utils/backend/parsing.py
new file mode 100644
index 000000000..ce3feede3
--- /dev/null
+++ b/nsight-graphics/agent-harness/cli_anything/nsight_graphics/utils/backend/parsing.py
@@ -0,0 +1,115 @@
+"""Parsing helpers for Nsight Graphics CLI output."""
+
+from __future__ import annotations
+
+import re
+from typing import Any, Optional
+
+from cli_anything.nsight_graphics.utils.backend.shared import _dedupe
+
+_ACTIVITY_ALIASES = {
+ "frame debugger": ("Frame Debugger", "Graphics Capture"),
+ "graphics capture": ("Graphics Capture", "Frame Debugger"),
+}
+
+
+def _extract_long_option(line: str) -> Optional[str]:
+ """Extract the primary long option token from a help line."""
+ match = re.search(r"(--[A-Za-z0-9-]+)", line)
+ return match.group(1) if match else None
+
+
+def parse_unified_help(text: str) -> dict[str, Any]:
+ """Parse `ngfx --help-all` output into structured metadata."""
+ activities: list[str] = []
+ platforms: list[str] = []
+ general_options: list[str] = []
+ activity_options: dict[str, list[str]] = {}
+ current_section: Optional[str] = None
+ current_activity: Optional[str] = None
+ collecting: Optional[str] = None
+
+ for raw_line in text.splitlines():
+ stripped = raw_line.strip()
+ if not stripped:
+ continue
+
+ if stripped == "General Options:":
+ current_section = "general"
+ current_activity = None
+ collecting = None
+ continue
+
+ if stripped.endswith("activity options:"):
+ current_section = "activity"
+ current_activity = stripped[: -len(" activity options:")]
+ activity_options.setdefault(current_activity, [])
+ collecting = None
+ continue
+
+ if stripped.startswith("--") or stripped.startswith("-"):
+ option = _extract_long_option(stripped)
+ if option and current_section == "general":
+ general_options.append(option)
+ if option == "--activity":
+ collecting = "activities"
+ elif option == "--platform":
+ collecting = "platforms"
+ else:
+ collecting = None
+ elif option and current_section == "activity" and current_activity:
+ activity_options.setdefault(current_activity, []).append(option)
+ collecting = None
+ else:
+ collecting = None
+ continue
+
+ if collecting == "activities":
+ lowered = stripped.lower()
+ if "should be one of" not in lowered and lowered not in {"of:", "one of:"}:
+ activities.append(stripped)
+ continue
+
+ if collecting == "platforms":
+ lowered = stripped.lower()
+ if "should be one of" not in lowered and lowered not in {"of:", "one of:"}:
+ platforms.append(stripped)
+ continue
+
+ return {
+ "activities": _dedupe(activities),
+ "platforms": _dedupe(platforms),
+ "general_options": _dedupe(general_options),
+ "activity_options": {
+ key: _dedupe(values) for key, values in activity_options.items()
+ },
+ }
+
+
+def parse_option_help(text: str) -> list[str]:
+ """Extract long options from arbitrary CLI help output."""
+ options: list[str] = []
+ for raw_line in text.splitlines():
+ option = _extract_long_option(raw_line.strip())
+ if option:
+ options.append(option)
+ return _dedupe(options)
+
+
+def resolve_activity_name(report: dict[str, Any], requested: str) -> str:
+ """Map a requested activity name onto the current Nsight installation."""
+ supported = report.get("supported_activities") or []
+ if not supported:
+ return requested
+
+ supported_lookup = {item.lower(): item for item in supported}
+ direct = supported_lookup.get(requested.lower())
+ if direct:
+ return direct
+
+ aliases = _ACTIVITY_ALIASES.get(requested.lower(), (requested,))
+ for alias in aliases:
+ resolved = supported_lookup.get(alias.lower())
+ if resolved:
+ return resolved
+ return requested
diff --git a/nsight-graphics/agent-harness/cli_anything/nsight_graphics/utils/backend/shared.py b/nsight-graphics/agent-harness/cli_anything/nsight_graphics/utils/backend/shared.py
new file mode 100644
index 000000000..fa89804f8
--- /dev/null
+++ b/nsight-graphics/agent-harness/cli_anything/nsight_graphics/utils/backend/shared.py
@@ -0,0 +1,54 @@
+"""Shared helpers for Nsight Graphics backend internals."""
+
+from __future__ import annotations
+
+import os
+import re
+import subprocess
+from typing import Iterable, Optional, Sequence
+
+
+def _command_string(args: Sequence[str]) -> str:
+ """Render a command for display."""
+ if os.name == "nt":
+ return subprocess.list2cmdline(list(args))
+ return " ".join(args)
+
+
+def _dedupe(values: Iterable[str]) -> list[str]:
+ """Deduplicate while preserving order."""
+ seen: set[str] = set()
+ result: list[str] = []
+ for value in values:
+ normalized = os.path.normcase(os.path.normpath(value))
+ if normalized in seen:
+ continue
+ seen.add(normalized)
+ result.append(value)
+ return result
+
+
+def _extract_version_from_text(text: str) -> Optional[str]:
+ """Extract a version string from CLI output or display text."""
+ match = re.search(r"(\d{4}\.\d+(?:\.\d+)?)", text)
+ if match:
+ return match.group(1)
+ return None
+
+
+def _extract_version_from_path(path: str) -> Optional[str]:
+ """Extract a version-like token from an installation path."""
+ return _extract_version_from_text(path)
+
+
+def _version_sort_key(version: Optional[str]) -> tuple[int, ...]:
+ """Convert a dotted version string into a sortable tuple."""
+ if not version:
+ return tuple()
+ parts: list[int] = []
+ for token in version.split("."):
+ try:
+ parts.append(int(token))
+ except ValueError:
+ parts.append(0)
+ return tuple(parts)
diff --git a/nsight-graphics/agent-harness/cli_anything/nsight_graphics/utils/nsight_graphics_backend.py b/nsight-graphics/agent-harness/cli_anything/nsight_graphics/utils/nsight_graphics_backend.py
index 121636f71..bfbde70e6 100644
--- a/nsight-graphics/agent-harness/cli_anything/nsight_graphics/utils/nsight_graphics_backend.py
+++ b/nsight-graphics/agent-harness/cli_anything/nsight_graphics/utils/nsight_graphics_backend.py
@@ -1,920 +1,99 @@
-"""Backend helpers for the official Nsight Graphics CLI tools."""
+"""Compatibility facade for the focused Nsight Graphics backend modules."""
from __future__ import annotations
-import glob
-import ctypes
-import os
-import platform
-import re
-import shutil
-import subprocess
-from pathlib import Path
-from typing import Any, Callable, Iterable, Optional, Sequence
-
-ENV_VAR = "NSIGHT_GRAPHICS_PATH"
-
-_BINARY_CANDIDATES = {
- "ngfx": ("ngfx.exe", "ngfx"),
- "ngfx_ui": ("ngfx-ui.exe", "ngfx-ui"),
- "ngfx_capture": ("ngfx-capture.exe", "ngfx-capture"),
- "ngfx_replay": ("ngfx-replay.exe", "ngfx-replay"),
-}
-
-INSTALL_INSTRUCTIONS = (
- "Nsight Graphics CLI tools were not found.\n"
- "Install NVIDIA Nsight Graphics and make sure ngfx.exe is available, or set "
- f"{ENV_VAR} to the install directory or executable path.\n"
- "Typical Windows location:\n"
- " C:\\Program Files\\NVIDIA Corporation\\Nsight Graphics <version>\\host\\windows-desktop-nomad-x64"
+from cli_anything.nsight_graphics.utils.backend.commands import (
+ build_split_capture_command,
+ build_unified_command,
+ ensure_at_most_one,
+ ensure_exactly_one,
+ format_env_values,
+ format_program_args,
+ require_binary,
+ require_launch_target,
+)
+from cli_anything.nsight_graphics.utils.backend.discovery import (
+ ENV_VAR,
+ INSTALL_INSTRUCTIONS,
+ _BINARY_CANDIDATES,
+ _candidate_dirs_from_env,
+ _default_windows_install_dirs,
+ _fixed_windows_drive_roots,
+ _normalized_install_key,
+ _override_value,
+ _primary_executable,
+ _read_registry_installations,
+ _scan_directory,
+ detect_tool_mode,
+ discover_binaries,
+ get_version,
+ list_installations,
+ probe_installation,
+)
+from cli_anything.nsight_graphics.utils.backend.execution import (
+ _combined_output,
+ activity_artifact_roots,
+ default_output_dir,
+ diff_snapshots,
+ run_command,
+ run_with_artifacts,
+ snapshot_files,
+)
+from cli_anything.nsight_graphics.utils.backend.parsing import (
+ _ACTIVITY_ALIASES,
+ _extract_long_option,
+ parse_option_help,
+ parse_unified_help,
+ resolve_activity_name,
+)
+from cli_anything.nsight_graphics.utils.backend.shared import (
+ _command_string,
+ _dedupe,
+ _extract_version_from_path,
+ _extract_version_from_text,
+ _version_sort_key,
)
-_ACTIVITY_ALIASES = {
- "frame debugger": ("Frame Debugger", "Graphics Capture"),
- "graphics capture": ("Graphics Capture", "Frame Debugger"),
-}
-
-
-def _command_string(args: Sequence[str]) -> str:
- """Render a command for display."""
- if platform.system() == "Windows":
- return subprocess.list2cmdline(list(args))
- return " ".join(args)
-
-
-def _dedupe(values: Iterable[str]) -> list[str]:
- """Deduplicate while preserving order."""
- seen: set[str] = set()
- result: list[str] = []
- for value in values:
- normalized = os.path.normcase(os.path.normpath(value))
- if normalized in seen:
- continue
- seen.add(normalized)
- result.append(value)
- return result
-
-
-def _normalized_install_key(path: str) -> str:
- """Normalize a path for install-root comparisons across slash styles."""
- normalized = os.path.normcase(os.path.normpath(path))
- return re.sub(r"[\\/]+", "/", normalized).rstrip("/")
-
-
-def _scan_directory(directory: str) -> dict[str, str]:
- """Scan a directory for known Nsight binaries."""
- found: dict[str, str] = {}
- base = Path(directory)
- if not base.is_dir():
- return found
- for key, candidates in _BINARY_CANDIDATES.items():
- for candidate in candidates:
- path = base / candidate
- if path.is_file():
- found[key] = str(path.resolve())
- break
- return found
-
-
-def _candidate_dirs_from_env(path_value: str) -> list[str]:
- """Resolve environment override into candidate directories."""
- if not path_value:
- return []
- path = Path(path_value)
- candidates: list[str] = []
- if path.is_file():
- candidates.append(str(path.parent))
- else:
- candidates.append(str(path))
- candidates.append(str(path / "host" / "windows-desktop-nomad-x64"))
- candidates.append(str(path / "windows-desktop-nomad-x64"))
- return _dedupe([p for p in candidates if Path(p).exists()])
-
-
-def _default_windows_install_dirs(
- glob_func: Callable[[str], list[str]],
-) -> list[str]:
- """Return default Windows install directories for Nsight Graphics."""
- drive_roots = _fixed_windows_drive_roots()
- if not drive_roots:
- drive_roots = ["C:"]
-
- patterns: list[str] = []
- for drive in drive_roots:
- patterns.extend(
- [
- f"{drive}/Program Files/NVIDIA Corporation/Nsight Graphics */host/windows-desktop-nomad-x64",
- f"{drive}/Program Files (x86)/NVIDIA Corporation/Nsight Graphics */host/windows-desktop-nomad-x64",
- ]
- )
- matches: list[str] = []
- for pattern in patterns:
- matches.extend(glob_func(pattern))
- return _dedupe(
- sorted(
- matches,
- key=lambda path: (_version_sort_key(_extract_version_from_path(path)), path),
- reverse=True,
- )
- )
-
-
-def _fixed_windows_drive_roots() -> list[str]:
- """Return fixed-drive roots such as C: and D: on Windows."""
- if platform.system() != "Windows":
- return []
- try:
- drive_mask = ctypes.windll.kernel32.GetLogicalDrives()
- get_drive_type = ctypes.windll.kernel32.GetDriveTypeW
- except Exception:
- return []
-
- DRIVE_FIXED = 3
- drives: list[str] = []
- for index in range(26):
- if not (drive_mask & (1 << index)):
- continue
- letter = chr(ord("A") + index)
- root = f"{letter}:\\"
- try:
- if get_drive_type(root) == DRIVE_FIXED:
- drives.append(f"{letter}:")
- except Exception:
- continue
- return drives
-
-
-def _read_registry_installations(
- platform_system: Optional[str] = None,
-) -> list[dict[str, Any]]:
- """Read Nsight Graphics install records from the Windows uninstall registry."""
- platform_system = platform.system() if platform_system is None else platform_system
- if platform_system != "Windows":
- return []
-
- try:
- import winreg
- except ImportError:
- return []
-
- uninstall_roots = [
- (winreg.HKEY_LOCAL_MACHINE, r"SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall"),
- (winreg.HKEY_LOCAL_MACHINE, r"SOFTWARE\WOW6432Node\Microsoft\Windows\CurrentVersion\Uninstall"),
- ]
-
- def _query_value(key, name: str) -> Optional[str]:
- try:
- value, _ = winreg.QueryValueEx(key, name)
- except OSError:
- return None
- if value is None:
- return None
- text = str(value).strip()
- return text or None
-
- records: list[dict[str, Any]] = []
- for hive, root in uninstall_roots:
- try:
- with winreg.OpenKey(hive, root) as root_key:
- index = 0
- while True:
- try:
- subkey_name = winreg.EnumKey(root_key, index)
- except OSError:
- break
- index += 1
- try:
- with winreg.OpenKey(root_key, subkey_name) as subkey:
- display_name = _query_value(subkey, "DisplayName")
- if not display_name or "Nsight Graphics" not in display_name:
- continue
- records.append(
- {
- "display_name": display_name,
- "display_version": _query_value(subkey, "DisplayVersion"),
- "install_location": _query_value(subkey, "InstallLocation"),
- "install_source": _query_value(subkey, "InstallSource"),
- "uninstall_string": _query_value(subkey, "UninstallString"),
- "publisher": _query_value(subkey, "Publisher"),
- "registry_key": f"HKLM\\{root}\\{subkey_name}",
- }
- )
- except OSError:
- continue
- except OSError:
- continue
- return records
-
-
-def _override_value(
- env: dict[str, str],
- nsight_path: Optional[str] = None,
-) -> str:
- """Resolve the effective override path from CLI or environment."""
- if nsight_path and nsight_path.strip():
- return nsight_path.strip()
- return env.get(ENV_VAR, "").strip()
-
-
-def discover_binaries(
- env: Optional[dict[str, str]] = None,
- which: Optional[Callable[[str], Optional[str]]] = None,
- glob_func: Optional[Callable[[str], list[str]]] = None,
- platform_system: Optional[str] = None,
- nsight_path: Optional[str] = None,
-) -> dict[str, Any]:
- """Discover available Nsight binaries."""
- env = os.environ if env is None else env
- which = shutil.which if which is None else which
- glob_func = glob.glob if glob_func is None else glob_func
- platform_system = platform.system() if platform_system is None else platform_system
-
- binaries: dict[str, Optional[str]] = {
- "ngfx": None,
- "ngfx_ui": None,
- "ngfx_capture": None,
- "ngfx_replay": None,
- }
- search_roots: list[str] = []
- override = _override_value(env, nsight_path=nsight_path)
-
- if override:
- override_path = Path(override)
- if override_path.is_file():
- for key, candidates in _BINARY_CANDIDATES.items():
- lowered = {name.lower() for name in candidates}
- if override_path.name.lower() in lowered:
- binaries[key] = str(override_path.resolve())
- break
- search_roots.extend(_candidate_dirs_from_env(override))
-
- for key, candidates in _BINARY_CANDIDATES.items():
- for candidate in candidates:
- resolved = which(candidate)
- if resolved:
- binaries[key] = binaries[key] or str(Path(resolved).resolve())
- search_roots.append(str(Path(resolved).resolve().parent))
- break
-
- if platform_system == "Windows":
- search_roots.extend(_default_windows_install_dirs(glob_func))
-
- for directory in _dedupe(search_roots):
- found = _scan_directory(directory)
- for key, value in found.items():
- binaries[key] = binaries[key] or value
-
- return {
- "binaries": binaries,
- "search_roots": _dedupe(search_roots),
- "env_override": env.get(ENV_VAR, "").strip() or None,
- "cli_override": nsight_path.strip() if nsight_path and nsight_path.strip() else None,
- "effective_override": override or None,
- }
-
-
-def list_installations(
- env: Optional[dict[str, str]] = None,
- which: Optional[Callable[[str], Optional[str]]] = None,
- glob_func: Optional[Callable[[str], list[str]]] = None,
- platform_system: Optional[str] = None,
- nsight_path: Optional[str] = None,
-) -> dict[str, Any]:
- """List installed Nsight Graphics directories and versions."""
- env = os.environ if env is None else env
- which = shutil.which if which is None else which
- glob_func = glob.glob if glob_func is None else glob_func
- platform_system = platform.system() if platform_system is None else platform_system
-
- discovered = discover_binaries(
- env=env,
- which=which,
- glob_func=glob_func,
- platform_system=platform_system,
- nsight_path=nsight_path,
- )
- selected_path = _primary_executable(discovered["binaries"])
-
- candidates: list[str] = []
- for root in discovered["search_roots"]:
- candidates.append(root)
- if platform_system == "Windows":
- candidates.extend(_default_windows_install_dirs(glob_func))
- if nsight_path:
- candidates.extend(_candidate_dirs_from_env(nsight_path))
- if env.get(ENV_VAR, "").strip():
- candidates.extend(_candidate_dirs_from_env(env[ENV_VAR]))
- for key, names in _BINARY_CANDIDATES.items():
- for name in names:
- resolved = which(name)
- if resolved:
- candidates.append(str(Path(resolved).resolve().parent))
- break
-
- installations: list[dict[str, Any]] = []
- installation_keys: set[str] = set()
- for directory in _dedupe(candidates):
- found = _scan_directory(directory)
- if not found:
- continue
- primary = _primary_executable(found)
- key = f"fs::{os.path.normcase(os.path.normpath(directory))}"
- installation_keys.add(key)
- installations.append(
- {
- "install_root": directory,
- "version": _extract_version_from_path(directory) or _extract_version_from_path(primary or ""),
- "tool_mode": detect_tool_mode(found),
- "selected": bool(primary and selected_path and os.path.normcase(primary) == os.path.normcase(selected_path)),
- "discovery_sources": ["filesystem"],
- "registered_only": False,
- "registry_key": None,
- "display_name": None,
- "display_version": None,
- "install_source": None,
- "binaries": {
- key: found.get(key) for key in ("ngfx", "ngfx_ui", "ngfx_capture", "ngfx_replay")
- },
- }
- )
-
- for record in _read_registry_installations(platform_system=platform_system):
- install_location = record.get("install_location")
- normalized_location = None
- if install_location:
- normalized_location = _normalized_install_key(install_location)
- guessed_version = (
- _extract_version_from_text(record.get("display_name") or "")
- or _extract_version_from_text(record.get("display_version") or "")
- )
-
- matched_entry = None
- if normalized_location:
- for item in installations:
- item_root = item.get("install_root")
- if not item_root:
- continue
- normalized_root = _normalized_install_key(item_root)
- if (
- normalized_root == normalized_location
- or normalized_root.startswith(normalized_location + "/")
- or normalized_location.startswith(normalized_root + "/")
- ):
- matched_entry = item
- break
- elif guessed_version:
- same_version = [
- item
- for item in installations
- if not item.get("registered_only") and item.get("version") == guessed_version
- ]
- if len(same_version) == 1:
- matched_entry = same_version[0]
-
- if matched_entry is not None:
- matched_entry["discovery_sources"] = _dedupe(
- list(matched_entry.get("discovery_sources", [])) + ["registry"]
- )
- matched_entry["display_name"] = record.get("display_name")
- matched_entry["display_version"] = record.get("display_version")
- matched_entry["registry_key"] = record.get("registry_key")
- matched_entry["install_source"] = record.get("install_source")
- if not matched_entry.get("version"):
- matched_entry["version"] = guessed_version
- continue
-
- registry_key = f"reg::{record['registry_key']}"
- if registry_key in installation_keys:
- continue
- installation_keys.add(registry_key)
- installations.append(
- {
- "install_root": install_location or None,
- "version": guessed_version,
- "tool_mode": "registered-only",
- "selected": False,
- "discovery_sources": ["registry"],
- "registered_only": True,
- "registry_key": record.get("registry_key"),
- "display_name": record.get("display_name"),
- "display_version": record.get("display_version"),
- "install_source": record.get("install_source"),
- "binaries": {
- "ngfx": None,
- "ngfx_ui": None,
- "ngfx_capture": None,
- "ngfx_replay": None,
- },
- }
- )
-
- installations.sort(
- key=lambda item: (
- not item["selected"],
- item.get("registered_only", False),
- item.get("version") or "",
- item.get("install_root") or item.get("display_name") or "",
- ),
- reverse=False,
- )
- return {
- "ok": bool(installations),
- "selected_executable": selected_path,
- "count": len(installations),
- "installations": installations,
- "cli_override": discovered.get("cli_override"),
- "env_override": discovered.get("env_override"),
- "registry_count": sum(1 for item in installations if "registry" in item.get("discovery_sources", [])),
- }
-
-
-def detect_tool_mode(binaries: dict[str, Optional[str]]) -> str:
- """Return compatibility mode for the discovered binaries."""
- if binaries.get("ngfx_capture") or binaries.get("ngfx_replay"):
- return "split"
- if binaries.get("ngfx"):
- return "unified"
- return "missing"
-
-
-def _extract_long_option(line: str) -> Optional[str]:
- """Extract the primary long option token from a help line."""
- match = re.search(r"(--[A-Za-z0-9-]+)", line)
- return match.group(1) if match else None
-
-
-def parse_unified_help(text: str) -> dict[str, Any]:
- """Parse `ngfx --help-all` output into structured metadata."""
- activities: list[str] = []
- platforms: list[str] = []
- general_options: list[str] = []
- activity_options: dict[str, list[str]] = {}
- current_section: Optional[str] = None
- current_activity: Optional[str] = None
- collecting: Optional[str] = None
-
- for raw_line in text.splitlines():
- stripped = raw_line.strip()
- if not stripped:
- continue
-
- if stripped == "General Options:":
- current_section = "general"
- current_activity = None
- collecting = None
- continue
-
- if stripped.endswith("activity options:"):
- current_section = "activity"
- current_activity = stripped[: -len(" activity options:")]
- activity_options.setdefault(current_activity, [])
- collecting = None
- continue
-
- if stripped.startswith("--") or stripped.startswith("-"):
- option = _extract_long_option(stripped)
- if option and current_section == "general":
- general_options.append(option)
- if option == "--activity":
- collecting = "activities"
- elif option == "--platform":
- collecting = "platforms"
- else:
- collecting = None
- elif option and current_section == "activity" and current_activity:
- activity_options.setdefault(current_activity, []).append(option)
- collecting = None
- else:
- collecting = None
- continue
-
- if collecting == "activities":
- lowered = stripped.lower()
- if "should be one of" not in lowered and lowered not in {"of:", "one of:"}:
- activities.append(stripped)
- continue
-
- if collecting == "platforms":
- lowered = stripped.lower()
- if "should be one of" not in lowered and lowered not in {"of:", "one of:"}:
- platforms.append(stripped)
- continue
-
- return {
- "activities": _dedupe(activities),
- "platforms": _dedupe(platforms),
- "general_options": _dedupe(general_options),
- "activity_options": {
- key: _dedupe(values) for key, values in activity_options.items()
- },
- }
-
-
-def parse_option_help(text: str) -> list[str]:
- """Extract long options from arbitrary CLI help output."""
- options: list[str] = []
- for raw_line in text.splitlines():
- option = _extract_long_option(raw_line.strip())
- if option:
- options.append(option)
- return _dedupe(options)
-
-
-def resolve_activity_name(report: dict[str, Any], requested: str) -> str:
- """Map a requested activity name onto the current Nsight installation."""
- supported = report.get("supported_activities") or []
- if not supported:
- return requested
-
- supported_lookup = {item.lower(): item for item in supported}
- direct = supported_lookup.get(requested.lower())
- if direct:
- return direct
-
- aliases = _ACTIVITY_ALIASES.get(requested.lower(), (requested,))
- for alias in aliases:
- resolved = supported_lookup.get(alias.lower())
- if resolved:
- return resolved
- return requested
-
-
-def _combined_output(result: dict[str, Any]) -> str:
- """Combine stdout and stderr for parsing."""
- stdout = result.get("stdout", "") or ""
- stderr = result.get("stderr", "") or ""
- return "\n".join(part for part in (stdout, stderr) if part)
-
-
-def run_command(
- args: Sequence[str],
- *,
- cwd: Optional[str] = None,
- timeout: int = 120,
-) -> dict[str, Any]:
- """Run a subprocess and normalize the result."""
- try:
- env = os.environ.copy()
- env.setdefault("NSIGHT_SUGGEST_GRAPHICS_CAPTURE", "0")
- proc = subprocess.run(
- list(args),
- capture_output=True,
- text=True,
- cwd=cwd,
- timeout=timeout,
- env=env,
- )
- return {
- "ok": proc.returncode == 0,
- "returncode": proc.returncode,
- "stdout": proc.stdout.strip(),
- "stderr": proc.stderr.strip(),
- "command": _command_string(args),
- }
- except FileNotFoundError as exc:
- return {
- "ok": False,
- "returncode": -1,
- "stdout": "",
- "stderr": str(exc),
- "command": _command_string(args),
- }
- except subprocess.TimeoutExpired:
- return {
- "ok": False,
- "returncode": -1,
- "stdout": "",
- "stderr": f"Command timed out after {timeout}s",
- "command": _command_string(args),
- }
-
-
-def _extract_version_from_text(text: str) -> Optional[str]:
- """Extract a version string from CLI output."""
- match = re.search(r"(\d{4}\.\d+(?:\.\d+)?)", text)
- if match:
- return match.group(1)
- return None
-
-
-def _extract_version_from_path(path: str) -> Optional[str]:
- """Extract a version-like token from the installation path."""
- return _extract_version_from_text(path)
-
-
-def _version_sort_key(version: Optional[str]) -> tuple[int, ...]:
- """Convert a dotted version string into a sortable tuple."""
- if not version:
- return tuple()
- parts: list[int] = []
- for token in version.split("."):
- try:
- parts.append(int(token))
- except ValueError:
- parts.append(0)
- return tuple(parts)
-
-
-def get_version(binaries: dict[str, Optional[str]]) -> Optional[str]:
- """Best-effort version detection from CLI output or path."""
- preferred = binaries.get("ngfx") or binaries.get("ngfx_capture") or binaries.get("ngfx_replay")
- if not preferred:
- return None
- result = run_command([preferred, "--version"], timeout=10)
- text = _combined_output(result)
- return _extract_version_from_text(text) or _extract_version_from_path(preferred)
-
-
-def _primary_executable(binaries: dict[str, Optional[str]]) -> Optional[str]:
- """Choose the preferred executable path to display."""
- return binaries.get("ngfx") or binaries.get("ngfx_capture") or binaries.get("ngfx_replay")
-
-
-def probe_installation(nsight_path: Optional[str] = None) -> dict[str, Any]:
- """Return an installation and capability report."""
- discovered = discover_binaries(nsight_path=nsight_path)
- binaries = discovered["binaries"]
- mode = detect_tool_mode(binaries)
- version = get_version(binaries)
-
- help_metadata = {
- "activities": [],
- "platforms": [],
- "general_options": [],
- "activity_options": {},
- }
- if binaries.get("ngfx"):
- help_result = run_command([binaries["ngfx"], "--help-all"], timeout=15)
- help_metadata.update(parse_unified_help(_combined_output(help_result)))
-
- capture_options: list[str] = []
- if binaries.get("ngfx_capture"):
- capture_help = run_command([binaries["ngfx_capture"], "--help"], timeout=15)
- capture_options = parse_option_help(_combined_output(capture_help))
-
- replay_options: list[str] = []
- if binaries.get("ngfx_replay"):
- replay_help = run_command([binaries["ngfx_replay"], "--help"], timeout=15)
- replay_options = parse_option_help(_combined_output(replay_help))
-
- warnings: list[str] = []
- host_platform = platform.system()
- if host_platform != "Windows":
- warnings.append(
- "V1 is only verified on Windows-hosted Nsight Graphics installations."
- )
- if mode == "missing":
- warnings.append(INSTALL_INSTRUCTIONS)
- if mode == "split" and not binaries.get("ngfx"):
- warnings.append(
- "Split capture/replay tools were found without ngfx.exe; launch, attach, "
- "GPU Trace, and C++ Capture helpers may be unavailable."
- )
-
- return {
- "ok": _primary_executable(binaries) is not None,
- "tool_mode": mode,
- "compatibility_mode": mode,
- "resolved_executable": _primary_executable(binaries),
- "version": version,
- "host_platform": host_platform,
- "verified_host": host_platform == "Windows",
- "supported_activities": help_metadata["activities"],
- "supported_platforms": help_metadata["platforms"],
- "general_options": help_metadata["general_options"],
- "activity_options": help_metadata["activity_options"],
- "split_binaries_present": {
- "ngfx_capture": bool(binaries.get("ngfx_capture")),
- "ngfx_replay": bool(binaries.get("ngfx_replay")),
- },
- "capture_options": capture_options,
- "replay_options": replay_options,
- "binaries": binaries,
- "search_roots": discovered["search_roots"],
- "env_override": discovered["env_override"],
- "cli_override": discovered.get("cli_override"),
- "effective_override": discovered.get("effective_override"),
- "warnings": warnings,
- }
-
-
-def require_binary(binaries: dict[str, Optional[str]], key: str) -> str:
- """Require a specific executable to exist."""
- path = binaries.get(key)
- if not path:
- raise RuntimeError(INSTALL_INSTRUCTIONS)
- return path
-
-
-def require_launch_target(*, project: Optional[str], exe: Optional[str]) -> None:
- """Require at least one launch target input."""
- if not project and not exe:
- raise ValueError("Specify --exe or set --project at the root level.")
-
-
-def ensure_exactly_one(label: str, flags: dict[str, bool]) -> str:
- """Validate that exactly one flag in the set is selected."""
- selected = [name for name, enabled in flags.items() if enabled]
- if len(selected) != 1:
- choices = ", ".join(flags.keys())
- raise ValueError(f"{label}: choose exactly one of {choices}.")
- return selected[0]
-
-
-def ensure_at_most_one(label: str, flags: dict[str, bool]) -> Optional[str]:
- """Validate that zero or one flags are selected."""
- selected = [name for name, enabled in flags.items() if enabled]
- if len(selected) > 1:
- choices = ", ".join(flags.keys())
- raise ValueError(f"{label}: choose at most one of {choices}.")
- return selected[0] if selected else None
-
-
-def format_env_values(envs: Sequence[str]) -> Optional[str]:
- """Format KEY=VALUE entries for ngfx.exe."""
- cleaned = [entry.strip() for entry in envs if entry and entry.strip()]
- if not cleaned:
- return None
- joined = "; ".join(cleaned)
- if not joined.endswith(";"):
- joined += ";"
- return joined
-
-
-def format_program_args(args: Sequence[str]) -> Optional[str]:
- """Format target executable arguments."""
- cleaned = [entry for entry in args if entry]
- if not cleaned:
- return None
- return subprocess.list2cmdline(cleaned)
-
-
-def build_unified_command(
- binaries: dict[str, Optional[str]],
- *,
- activity: Optional[str] = None,
- project: Optional[str] = None,
- output_dir: Optional[str] = None,
- hostname: Optional[str] = None,
- platform_name: Optional[str] = None,
- exe: Optional[str] = None,
- working_dir: Optional[str] = None,
- args: Sequence[str] = (),
- envs: Sequence[str] = (),
- attach_pid: Optional[int] = None,
- launch_detached: bool = False,
- extra_args: Sequence[str] = (),
-) -> list[str]:
- """Build a command line for the unified ngfx.exe CLI."""
- ngfx = require_binary(binaries, "ngfx")
- command: list[str] = [ngfx]
- if hostname:
- command.extend(["--hostname", hostname])
- if project:
- command.extend(["--project", project])
- if output_dir:
- command.extend(["--output-dir", output_dir])
- if activity:
- command.extend(["--activity", activity])
- if platform_name:
- command.extend(["--platform", platform_name])
- if launch_detached:
- command.append("--launch-detached")
- if attach_pid is not None:
- command.extend(["--attach-pid", str(attach_pid)])
- if exe:
- command.extend(["--exe", exe])
- if working_dir:
- command.extend(["--dir", working_dir])
- formatted_args = format_program_args(args)
- if formatted_args:
- command.extend(["--args", formatted_args])
- formatted_env = format_env_values(envs)
- if formatted_env:
- command.extend(["--env", formatted_env])
- command.extend(extra_args)
- return command
-
-
-def build_split_capture_command(
- binaries: dict[str, Optional[str]],
- *,
- exe: str,
- output_dir: Optional[str] = None,
- working_dir: Optional[str] = None,
- args: Sequence[str] = (),
- envs: Sequence[str] = (),
- wait_seconds: Optional[int] = None,
- wait_frames: Optional[int] = None,
- wait_hotkey: bool = False,
- frame_count: int = 1,
-) -> list[str]:
- """Build a command line for the split ngfx-capture tool."""
- capture = require_binary(binaries, "ngfx_capture")
- command: list[str] = [capture, "--exe", exe, "--frame-count", str(frame_count)]
- if output_dir:
- command.extend(["--output-dir", output_dir])
- if working_dir:
- command.extend(["--working-dir", working_dir])
- formatted_args = format_program_args(args)
- if formatted_args:
- command.extend(["--args", formatted_args])
- formatted_env = format_env_values(envs)
- if formatted_env:
- command.extend(["--env", formatted_env])
-
- ensure_exactly_one(
- "frame trigger",
- {
- "wait_seconds": wait_seconds is not None,
- "wait_frames": wait_frames is not None,
- "wait_hotkey": wait_hotkey,
- },
- )
- if wait_seconds is not None:
- command.extend(["--capture-countdown-timer", str(wait_seconds * 1000)])
- elif wait_frames is not None:
- command.extend(["--capture-frame", str(wait_frames)])
- else:
- command.append("--capture-hotkey")
- return command
-
-
-def default_output_dir() -> str:
- """Best-effort default output root used by the harness."""
- return str((Path.home() / "Documents" / "NVIDIA Nsight Graphics").resolve())
-
-
-def activity_artifact_roots(activity: str, output_dir: Optional[str]) -> list[str]:
- """Return directories to scan for generated artifacts."""
- base = Path(default_output_dir())
- roots: list[str] = []
- if output_dir:
- roots.append(str(Path(output_dir).resolve()))
- else:
- roots.append(str(base))
-
- normalized = activity.lower()
- if normalized in {"frame debugger", "graphics capture"}:
- roots.extend([str(base), str(base / "GraphicsCaptures")])
- elif normalized == "gpu trace profiler":
- if not output_dir:
- roots.append(str(base / "GPUTrace"))
- elif normalized == "generate c++ capture":
- roots.append(str(base / "CppCaptures"))
- return _dedupe(roots)
-
-
-def snapshot_files(roots: Sequence[str]) -> dict[str, tuple[int, int]]:
- """Snapshot file mtimes and sizes under the roots."""
- snapshot: dict[str, tuple[int, int]] = {}
- for root in roots:
- root_path = Path(root)
- if not root_path.is_dir():
- continue
- for path in root_path.rglob("*"):
- if not path.is_file():
- continue
- try:
- stat = path.stat()
- except OSError:
- continue
- snapshot[str(path.resolve())] = (stat.st_mtime_ns, stat.st_size)
- return snapshot
-
-
-def diff_snapshots(
- before: dict[str, tuple[int, int]],
- after: dict[str, tuple[int, int]],
-) -> list[dict[str, Any]]:
- """Return non-empty files that were created or updated."""
- artifacts: list[dict[str, Any]] = []
- for path, (mtime_ns, size) in sorted(after.items()):
- previous = before.get(path)
- if size <= 0:
- continue
- if previous is None or previous != (mtime_ns, size):
- artifacts.append(
- {
- "path": path,
- "size": size,
- "mtime_ns": mtime_ns,
- }
- )
- return artifacts
-
-
-def run_with_artifacts(
- args: Sequence[str],
- *,
- output_roots: Sequence[str],
- cwd: Optional[str] = None,
- timeout: int = 300,
-) -> dict[str, Any]:
- """Run a command and discover artifacts under the supplied roots."""
- before = snapshot_files(output_roots)
- result = run_command(args, cwd=cwd, timeout=timeout)
- after = snapshot_files(output_roots)
- result["artifacts"] = diff_snapshots(before, after)
- result["artifact_count"] = len(result["artifacts"])
- return result
+__all__ = [
+ "ENV_VAR",
+ "INSTALL_INSTRUCTIONS",
+ "_ACTIVITY_ALIASES",
+ "_BINARY_CANDIDATES",
+ "_candidate_dirs_from_env",
+ "_combined_output",
+ "_command_string",
+ "_dedupe",
+ "_default_windows_install_dirs",
+ "_extract_long_option",
+ "_extract_version_from_path",
+ "_extract_version_from_text",
+ "_fixed_windows_drive_roots",
+ "_normalized_install_key",
+ "_override_value",
+ "_primary_executable",
+ "_read_registry_installations",
+ "_scan_directory",
+ "_version_sort_key",
+ "activity_artifact_roots",
+ "build_split_capture_command",
+ "build_unified_command",
+ "default_output_dir",
+ "detect_tool_mode",
+ "diff_snapshots",
+ "discover_binaries",
+ "ensure_at_most_one",
+ "ensure_exactly_one",
+ "format_env_values",
+ "format_program_args",
+ "get_version",
+ "list_installations",
+ "parse_option_help",
+ "parse_unified_help",
+ "probe_installation",
+ "require_binary",
+ "require_launch_target",
+ "resolve_activity_name",
+ "run_command",
+ "run_with_artifacts",
+ "snapshot_files",
+]