gpu-stack-inspector 0.1.0__py3-none-any.whl

gpu_stack_inspector/reports/markdown.py

@@ -0,0 +1,182 @@
+"""Markdown output: an issue-ready dossier of an already redacted snapshot.
+
+Collected text is escaped so a path containing ``|`` cannot break a table and ``<tag>``
+cannot become HTML in an issue tracker; values go in code spans whose fence is longer
+than any backtick run they contain.
+"""
+
+from __future__ import annotations
+
+import re
+from collections import Counter
+
+from gpu_stack_inspector.models import Finding, InterpreterFacts, Snapshot, Status
+from gpu_stack_inspector.reports.terminal import redaction_line, runtime_summary
+from gpu_stack_inspector.rules.comparison import torch_build_label
+
+_SPECIAL = re.compile(r"([\\`*_\[\]<>|#])")
+_PROBLEMS = (Status.FAIL, Status.WARN, Status.UNKNOWN)
+_LABEL = {
+    Status.FAIL: "FAIL",
+    Status.WARN: "WARN",
+    Status.UNKNOWN: "UNKNOWN",
+    Status.PASS: "PASS",
+    Status.NOT_APPLICABLE: "N/A",
+    Status.NOT_TESTED: "NOT TESTED",
+}
+
+
+def text(value: str) -> str:
+    """Plain text that Markdown and HTML will not interpret; one line."""
+    return _SPECIAL.sub(r"\\\1", " ".join(value.split()))
+
+
+def code(value: str) -> str:
+    """An inline code span that survives any backticks inside the value."""
+    flat = " ".join(value.split())
+    longest = max((len(run) for run in re.findall(r"`+", flat)), default=0)
+    fence = "`" * (longest + 1)
+    padding = " " if flat.startswith("`") or flat.endswith("`") else ""
+    return f"{fence}{padding}{flat}{padding}{fence}"
+
+
+def _cell(value: str | None, *, as_code: bool = False) -> str:
+    if value is None:
+        return "—"
+    return code(value) if as_code else text(value)
+
+
+def render_markdown(snapshot: Snapshot) -> str:
+    lines: list[str] = ["# GPU Stack Inspector report", ""]
+    lines.append(
+        f"Generated by gpu-stack-inspector {text(snapshot.tool_version)} on "
+        f"{text(snapshot.created_at)}. Read-only: nothing was installed or changed."
+    )
+    redacted = redaction_line(snapshot)
+    if redacted:
+        lines.append(f"{text(redacted)}.")
+    lines += ["", *_summary(snapshot), "", *_system(snapshot)]
+    if snapshot.interpreters:
+        lines += ["", *_environments(snapshot.interpreters)]
+    if snapshot.comparison:
+        lines += ["", *_differences(snapshot)]
+    if snapshot.findings:
+        lines += ["", *_findings(snapshot)]
+    if snapshot.probe_failures:
+        lines += ["", "## Not checked", ""]
+        lines += [f"- {text(f.probe)}: {text(f.detail)}" for f in snapshot.probe_failures]
+    return "\n".join(lines) + "\n"
+
+
+def _summary(snapshot: Snapshot) -> list[str]:
+    lines = ["## Summary", ""]
+    problems = [f for f in snapshot.findings if f.status in _PROBLEMS and not f.caused_by]
+    order = {status: i for i, status in enumerate(_PROBLEMS)}
+    for finding in sorted(problems, key=lambda f: order[f.status]):
+        where = "" if finding.subject == "host" else f" ({text(finding.subject)})"
+        lines.append(
+            f"- **{_LABEL[finding.status]}** {code(finding.id)}{where}: {text(finding.summary)}"
+        )
+    if not problems:
+        lines.append("No problems found." if snapshot.findings else "No checks were run.")
+    counts = Counter(f.status for f in snapshot.findings)
+    if snapshot.findings:
+        lines += [
+            "",
+            f"{counts[Status.FAIL]} failed, {counts[Status.WARN]} warnings, "
+            f"{counts[Status.UNKNOWN]} unknown, {counts[Status.PASS]} passed.",
+        ]
+    return lines
+
+
+def _system(snapshot: Snapshot) -> list[str]:
+    rows: list[tuple[str, str]] = []
+    host = snapshot.host
+    if host is not None:
+        system = " · ".join(p for p in (f"{host.system} {host.machine}", host.distribution) if p)
+        rows.append(("OS", text(system)))
+        rows.append(("Kernel", _cell(host.kernel)))
+    nvidia = snapshot.nvidia
+    if nvidia is not None:
+        if nvidia.smi_path is None:
+            rows.append(("NVIDIA driver", "nvidia-smi not found"))
+        else:
+            driver = _cell(nvidia.driver_version)
+            cuda = _cell(nvidia.max_cuda_version)
+            rows.append(("NVIDIA driver", f"{driver} (supports CUDA up to {cuda})"))
+        for gpu in nvidia.gpus:
+            memory = f"{gpu.memory_total_mib} MiB" if gpu.memory_total_mib is not None else "? MiB"
+            details = f"{text(gpu.name)}, {memory}, compute {_cell(gpu.compute_capability)}"
+            rows.append((f"GPU {gpu.index}", details))
+    toolkit = snapshot.toolkit
+    if toolkit is not None:
+        rows.append(("nvcc", _cell(toolkit.nvcc_version) if toolkit.nvcc_path else "not installed"))
+        for found in toolkit.toolkits:
+            rows.append(("CUDA toolkit", f"{code(found.path)} ({_cell(found.version)})"))
+    for variable in snapshot.cuda_environment:
+        rows.append((text(variable.name), code(variable.value) if variable.value else '`""`'))
+    if not rows:
+        return ["## System", "", "Not inspected."]
+    return ["## System", "", "| | |", "| --- | --- |", *(f"| {k} | {v} |" for k, v in rows)]
+
+
+def _environments(interpreters: tuple[InterpreterFacts, ...]) -> list[str]:
+    lines = [
+        "## Environments",
+        "",
+        "| | Path | Python | Kind | torch | Build | Runtime |",
+        "| --- | --- | --- | --- | --- | --- | --- |",
+    ]
+    for i in interpreters:
+        kind = ", ".join(k for k, on in (("conda", i.conda), ("venv", i.virtualenv)) if on) or "—"
+        torch = i.torch.version if i.torch else None
+        runtime = runtime_summary(i) or "not tested"
+        lines.append(
+            f"| {text(i.label)} | {code(i.path)} | {_cell(i.version)} | {kind} "
+            f"| {_cell(torch)} | {_cell(torch_build_label(i))} | {text(runtime)} |"
+        )
+    return lines
+
+
+def _differences(snapshot: Snapshot) -> list[str]:
+    rows = [row for row in snapshot.comparison if row.differs]
+    labels = [text(i.label) for i in snapshot.interpreters]
+    lines = ["## Differences", ""]
+    if not rows:
+        return [*lines, "No differences in the compared fields."]
+    lines.append("| Field | " + " | ".join(labels) + " |")
+    lines.append("| --- |" + " --- |" * len(labels))
+    for row in rows:
+        values = " | ".join(_cell(value) for value in row.values)
+        lines.append(f"| {text(row.field)} | {values} |")
+    return lines
+
+
+def _findings(snapshot: Snapshot) -> list[str]:
+    paths = {i.label: i.path for i in snapshot.interpreters}
+    lines = ["## Findings"]
+    for subject in ["host", *paths, "comparison"]:
+        group = [f for f in snapshot.findings if f.subject == subject]
+        if not group:
+            continue
+        heading = {"host": "Host", "comparison": "Comparison"}.get(subject)
+        lines += ["", f"### {heading or f'{text(subject)} ({code(paths[subject])})'}", ""]
+        for finding in group:
+            lines += _finding(finding)
+    return lines
+
+
+def _finding(finding: Finding) -> list[str]:
+    summary = text(finding.summary)
+    if finding.caused_by:
+        summary += f" (follows from {code(finding.caused_by)})"
+    lines = [f"- **{_LABEL[finding.status]}** {code(finding.id)} {summary}"]
+    if finding.status not in _PROBLEMS:
+        return lines
+    lines.append(f"  - Why: {text(finding.reason)}")
+    if finding.recommended_action:
+        lines.append(f"  - Next: {text(finding.recommended_action)}")
+    if finding.verify_command:
+        lines.append(f"  - Check: {code(finding.verify_command)}")
+    lines += [f"  - Note: {text(limitation)}" for limitation in finding.limitations]
+    return lines

gpu_stack_inspector/reports/terminal.py

@@ -0,0 +1,298 @@
+"""Terminal output: a short human summary of an already redacted snapshot.
+
+Collected text is always added as plain ``Text``, never as Rich markup, so a path or GPU
+name containing ``[bold]`` is printed as it is instead of being interpreted.
+"""
+
+from __future__ import annotations
+
+from collections import Counter
+
+from rich.console import Console
+from rich.table import Table
+from rich.text import Text
+
+from gpu_stack_inspector.models import (
+    Finding,
+    HostFacts,
+    InterpreterFacts,
+    NvidiaFacts,
+    Snapshot,
+    Status,
+    ToolkitFacts,
+)
+from gpu_stack_inspector.rules.torch_build import TorchBuild, TorchBuildKind, classify_torch
+
+_INDENT = "         "
+
+
+def _render_header(snapshot: Snapshot, console: Console) -> None:
+    console.print(Text(f"GPU Stack Inspector {snapshot.tool_version}", style="bold"))
+    console.print(_row("Host", _host(snapshot.host)))
+    nvidia_lines = _nvidia(snapshot.nvidia)
+    console.print(_row("NVIDIA", nvidia_lines[0]))
+    for line in nvidia_lines[1:]:
+        console.print(Text(_INDENT + line))
+    console.print(_row("Toolkit", _toolkit(snapshot.toolkit)))
+
+
+_REDACTION_NAMES = {
+    "home_path": ("home path", "home paths"),
+    "user_name": ("user name", "user names"),
+    "host_name": ("host name", "host names"),
+    "secret_value": ("secret value", "secret values"),
+    "url_credentials": ("URL credential", "URL credentials"),
+    "token": ("token", "tokens"),
+}
+
+
+def redaction_line(snapshot: Snapshot) -> str | None:
+    """'Redacted from this output: 3 home paths, 1 secret value', or None if nothing was."""
+    if not snapshot.redactions:
+        return None
+    parts = []
+    for item in snapshot.redactions:
+        singular, plural = _REDACTION_NAMES.get(item.kind, (item.kind, item.kind))
+        parts.append(f"{item.count} {singular if item.count == 1 else plural}")
+    return "Redacted from this output: " + ", ".join(parts)
+
+
+def _render_failures(snapshot: Snapshot, console: Console) -> None:
+    if snapshot.probe_failures:
+        console.print()
+        console.print(Text("Could not check:", style="bold"))
+        for failure in snapshot.probe_failures:
+            console.print(Text(f"  {failure.probe}: {failure.detail}"))
+    line = redaction_line(snapshot)
+    if line:
+        console.print(Text(line, style="dim"))
+
+
+def render_compare(snapshot: Snapshot, console: Console, *, show_all: bool = False) -> None:
+    """The comparison table (only the fields that differ, unless ``show_all``), then findings."""
+    _render_header(snapshot, console)
+    console.print()
+    for interpreter in snapshot.interpreters:
+        console.print(Text.assemble((f"{interpreter.label:<3}", "bold"), interpreter.path))
+    rows = [row for row in snapshot.comparison if show_all or row.differs]
+    console.print()
+    if not rows:
+        console.print(Text("No differences in the compared fields."))
+    else:
+        table = Table(box=None, pad_edge=False, show_edge=False)
+        table.add_column("Field", no_wrap=True)
+        for interpreter in snapshot.interpreters:
+            table.add_column(interpreter.label, overflow="fold")
+        for row in rows:
+            style = "bold" if row.differs else "dim"
+            values = [Text(value if value is not None else "—") for value in row.values]
+            table.add_row(Text(row.field, style=style), *values)
+        console.print(table)
+        hidden = len(snapshot.comparison) - len(rows)
+        if hidden:
+            console.print(Text(f"{hidden} identical fields hidden; --all shows them.", style="dim"))
+    if snapshot.findings:
+        _render_findings(snapshot, console)
+    _render_failures(snapshot, console)
+
+
+def render_terminal(snapshot: Snapshot, console: Console) -> None:
+    _render_header(snapshot, console)
+    if snapshot.cuda_environment:
+        values = ", ".join(
+            f"{v.name}={v.value}" if v.value else f'{v.name}="" (hides every GPU)'
+            for v in snapshot.cuda_environment
+        )
+        console.print(_row("CUDA env", values))
+    for interpreter in snapshot.interpreters:
+        console.print()
+        console.print(Text.assemble((f"{interpreter.label:<3}", "bold"), interpreter.path))
+        console.print(Text("   " + _interpreter(interpreter)))
+    if snapshot.findings:
+        _render_findings(snapshot, console)
+    _render_failures(snapshot, console)
+
+
+def _row(name: str, value: str) -> Text:
+    return Text.assemble((f"{name:<9}", "bold"), value)
+
+
+def _host(host: HostFacts | None) -> str:
+    if host is None:
+        return "not inspected"
+    parts = [f"{host.system} {host.machine}"]
+    if host.distribution:
+        parts.append(host.distribution)
+    if host.kernel:
+        parts.append(f"kernel {host.kernel}")
+    if host.wsl:
+        parts.append("WSL")
+    return " · ".join(parts)
+
+
+def _nvidia(nvidia: NvidiaFacts | None) -> list[str]:
+    if nvidia is None:
+        return ["not inspected"]
+    if nvidia.smi_path is None:
+        return ["nvidia-smi not found (no NVIDIA driver tools on PATH)"]
+    if nvidia.driver_version is None and not nvidia.gpus:
+        return ["nvidia-smi did not answer (see below)"]
+    summary = (
+        f"driver {nvidia.driver_version or 'unknown'} · "
+        f"supports CUDA up to {nvidia.max_cuda_version or 'unknown'}"
+    )
+    gpus = [
+        f"GPU {gpu.index}: {gpu.name}"
+        + f" ({gpu.memory_total_mib if gpu.memory_total_mib is not None else '?'} MiB,"
+        + f" compute {gpu.compute_capability or 'unknown'})"
+        for gpu in nvidia.gpus
+    ]
+    return [summary, *(gpus or ["no GPU visible to the driver"])]
+
+
+def _toolkit(toolkit: ToolkitFacts | None) -> str:
+    if toolkit is None:
+        return "not inspected"
+    nvcc = (
+        f"nvcc {toolkit.nvcc_version or 'unknown version'} ({toolkit.nvcc_path})"
+        if toolkit.nvcc_path
+        else "no nvcc on PATH"
+    )
+    directories = ", ".join(
+        f"{t.path} ({t.version or 'unknown version'})" for t in toolkit.toolkits
+    )
+    return f"{nvcc} · {directories or 'no CUDA toolkit directories found'}"
+
+
+def _interpreter(interpreter: InterpreterFacts) -> str:
+    if interpreter.version is None:
+        return "could not be inspected (see below)"
+    kind = [interpreter.implementation or "python"]
+    if interpreter.conda:
+        kind.append("conda")
+    if interpreter.virtualenv:
+        kind.append("venv")
+    wheels = sum(d.name.startswith("nvidia-") for d in interpreter.distributions)
+    parts = [
+        f"Python {interpreter.version} ({', '.join(kind)})",
+        _torch(interpreter),
+        f"{wheels} nvidia-* wheels",
+    ]
+    runtime = runtime_summary(interpreter)
+    if runtime:
+        parts.append(runtime)
+    return " · ".join(parts)
+
+
+def runtime_summary(interpreter: InterpreterFacts) -> str | None:
+    """What probe --runtime found, in a few words; None when it was not run."""
+    runtime = interpreter.runtime
+    if runtime is None:
+        return None
+    if runtime.tensor_ok:
+        device = runtime.devices[0].name if runtime.devices else "the GPU"
+        return f"CUDA works on {device}"
+    if runtime.cuda_available is False:
+        return "CUDA unavailable"
+    failed = next((step.step for step in runtime.steps if not step.ok), None)
+    return f"runtime check failed at '{failed}'" if failed else "runtime check failed"
+
+
+def _torch(interpreter: InterpreterFacts) -> str:
+    if interpreter.torch is None:
+        listed = next((d for d in interpreter.distributions if d.name == "torch"), None)
+        return f"torch {listed.version} (build not inspected)" if listed else "no torch"
+    return f"torch {interpreter.torch.version} ({_build(classify_torch(interpreter.torch))})"
+
+
+def _build(build: TorchBuild) -> str:
+    """Say what the metadata shows, and only that: no CUDA operation has run yet."""
+    if build.kind is TorchBuildKind.CUDA:
+        target = f"CUDA {build.cuda_version}" if build.cuda_version else "CUDA"
+        text = f"{target} build"
+    elif build.kind is TorchBuildKind.CPU:
+        text = "CPU-only build"
+    elif build.kind is TorchBuildKind.ROCM:
+        text = "ROCm build, not checked by this tool"
+    else:
+        text = "build unknown"
+    if build.conflicts:
+        text += f"; {build.conflicts[0]}"
+    elif build.kind is not TorchBuildKind.UNKNOWN and build.confidence.value != "high":
+        text += f", {build.confidence.value} confidence"
+    return text
+
+
+_LABELS = {
+    Status.FAIL: ("FAIL", "bold red"),
+    Status.WARN: ("WARN", "yellow"),
+    Status.UNKNOWN: ("UNKNOWN", "magenta"),
+    Status.PASS: ("PASS", "green"),
+    Status.NOT_APPLICABLE: ("N/A", "dim"),
+    Status.NOT_TESTED: ("NOT TESTED", "dim"),
+}
+_PROBLEMS = frozenset({Status.FAIL, Status.WARN, Status.UNKNOWN})
+
+
+def _render_findings(snapshot: Snapshot, console: Console) -> None:
+    """Findings per subject (host, then each interpreter) in evaluation order.
+
+    Problems show their reason, the next step and how to check it; consequences of a
+    root cause are dimmed and say which finding they follow from.
+    """
+    paths = {interpreter.label: interpreter.path for interpreter in snapshot.interpreters}
+    subjects = ["host", *paths, "comparison"]
+    console.print()
+    console.print(Text("Findings", style="bold"))
+    for subject in subjects:
+        group = [f for f in snapshot.findings if f.subject == subject]
+        if not group:
+            continue
+        heading = (
+            "Host"
+            if subject == "host"
+            else "Comparison"
+            if subject == "comparison"
+            else f"{subject}  {paths[subject]}"
+        )
+        console.print(Text(heading, style="bold"))
+        table = Table.grid(padding=(0, 1))
+        table.add_column(width=10, no_wrap=True)
+        table.add_column(width=13, no_wrap=True)  # GSI-TORCH-002 is the longest code
+        # Fold, never crop: people copy the commands and paths shown here.
+        table.add_column(overflow="fold")
+        for finding in group:
+            _add_finding(table, finding)
+        console.print(table)
+    console.print(Text(_tally(snapshot.findings)))
+
+
+def _add_finding(table: Table, finding: Finding) -> None:
+    label, style = _LABELS[finding.status]
+    summary = finding.summary
+    if finding.caused_by:
+        summary += f" (follows from {finding.caused_by})"
+        style = "dim"
+    table.add_row(Text(label, style=style), Text(finding.id, style="dim"), Text(summary))
+    if finding.status not in _PROBLEMS:
+        return
+    details = [finding.reason]
+    if finding.recommended_action:
+        details.append(f"Next:  {finding.recommended_action}")
+    if finding.verify_command:
+        details.append(f"Check: {finding.verify_command}")
+    details.extend(f"Note:  {limitation}" for limitation in finding.limitations)
+    for detail in details:
+        table.add_row(Text(""), Text(""), Text(detail))
+
+
+def _tally(findings: tuple[Finding, ...]) -> str:
+    counts = Counter(f.status for f in findings)
+    parts = [
+        f"{counts[Status.FAIL]} failed",
+        f"{counts[Status.WARN]} warning{'' if counts[Status.WARN] == 1 else 's'}",
+        f"{counts[Status.UNKNOWN]} unknown",
+        f"{counts[Status.PASS]} passed",
+        f"{counts[Status.NOT_APPLICABLE] + counts[Status.NOT_TESTED]} not applicable or not tested",
+    ]
+    return "Summary: " + " · ".join(parts)

gpu_stack_inspector/rules/__init__.py

@@ -0,0 +1 @@
+"""Pure inference: functions of collected facts. Nothing here runs commands or reads files."""

gpu_stack_inspector/rules/catalog.py

@@ -0,0 +1,21 @@
+"""The built-in rules. Modules register into RULES when imported, in evaluation order."""
+
+from __future__ import annotations
+
+import importlib
+
+from gpu_stack_inspector.rules.engine import Registry
+
+RULES = Registry()
+
+_MODULES = ("host", "interpreters", "compatibility", "differences")
+"""Evaluation order: the machine first, then each interpreter, then how they fit together,
+then how the interpreters differ from each other.
+Kept as data on purpose: import sorting would otherwise reorder the rules."""
+
+
+def builtin_rules() -> Registry:
+    """All built-in rules, in evaluation order."""
+    for name in _MODULES:
+        importlib.import_module(f"gpu_stack_inspector.rules.{name}")
+    return RULES

gpu_stack_inspector/rules/comparison.py

@@ -0,0 +1,73 @@
+"""Field-by-field comparison of inspected interpreters. Pure: facts in, rows out."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+
+from gpu_stack_inspector.models import FieldComparison, InterpreterFacts
+from gpu_stack_inspector.rules.torch_build import TorchBuildKind, classify_torch
+
+
+def _flag(value: bool | None) -> str | None:
+    return None if value is None else ("yes" if value else "no")
+
+
+_INTERPRETER_FIELDS: tuple[tuple[str, Callable[[InterpreterFacts], str | None]], ...] = (
+    ("Python", lambda i: i.version),
+    ("implementation", lambda i: i.implementation),
+    ("conda env", lambda i: _flag(i.conda)),
+    ("venv", lambda i: _flag(i.virtualenv)),
+    ("platform", lambda i: i.platform),
+    ("user site", lambda i: _flag(i.user_site)),
+    ("PYTHONPATH set", lambda i: _flag(i.pythonpath_set)),
+)
+
+
+def torch_build_label(interpreter: InterpreterFacts) -> str | None:
+    """The build in plain words ("CUDA 12.8", "CPU only", "not installed"…)."""
+    if interpreter.version is None:
+        return None
+    build = classify_torch(interpreter.torch)
+    if build.kind is TorchBuildKind.CUDA:
+        return f"CUDA {build.cuda_version}" if build.cuda_version else "CUDA"
+    return {
+        TorchBuildKind.CPU: "CPU only",
+        TorchBuildKind.ROCM: "ROCm",
+        TorchBuildKind.UNKNOWN: "unknown",
+        TorchBuildKind.MISSING: "not installed",
+    }[build.kind]
+
+
+_TORCH_FIELDS: tuple[tuple[str, Callable[[InterpreterFacts], str | None]], ...] = (
+    ("torch", lambda i: i.torch.version if i.torch else None),
+    ("torch build", torch_build_label),
+    ("torch location", lambda i: i.torch.location if i.torch else None),
+)
+
+
+def _package_version(interpreter: InterpreterFacts, name: str) -> str | None:
+    """The installed version; several installs of one package (shadowing) are all named."""
+    versions = [d.version for d in interpreter.distributions if d.name == name]
+    if not versions:
+        return None
+    if len(versions) == 1:
+        return versions[0]
+    return f"{', '.join(sorted(set(versions)))} ({len(versions)} installs)"
+
+
+def compare_interpreters(interpreters: Sequence[InterpreterFacts]) -> tuple[FieldComparison, ...]:
+    """Rows for every compared field, in a fixed order; ``differs`` marks disagreement.
+
+    After the interpreter and torch rows comes one row per GPU-relevant package found in
+    any of them, alphabetically; ``None`` there means "not installed".
+    """
+    fixed = tuple(
+        FieldComparison(name, tuple(value(i) for i in interpreters))
+        for name, value in (*_INTERPRETER_FIELDS, *_TORCH_FIELDS)
+    )
+    names = sorted({d.name for i in interpreters for d in i.distributions} - {"torch"})
+    packages = tuple(
+        FieldComparison(name, tuple(_package_version(i, name) for i in interpreters))
+        for name in names
+    )
+    return fixed + packages