Skip to content

A GPU task manager for Windows, Linux, and WSL: per-process VRAM, GPU activity, and LLM model/KV-cache insights (Windows AMD and NVIDIA).

Python

Add gputaskman diff to compare two JSON snapshots (#6)

Scott Hanselmanccfec5b49593
diff --git a/AGENTS.md b/AGENTS.md
index 6e0b4d6..fe6381e 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -55,6 +55,7 @@ cli.py ──► Collector.sample() (collector.py)
├─ LLM detail llm.py: buffer logs, ServerProber (local APIs), build_view()
└─ app adapters handy.py (settings + bounded log tail)
──► Snapshot ──► app.py (Textual TUI) / report.py (text and JSON)
+cli.py diff ──► diff.py: compares two saved --json snapshots (no collection)
```
The backend is chosen at import time in `collector.py`: `BACKEND` is `wddm` on Windows, `nvml` on
@@ -70,7 +71,8 @@ identify everything immediately; the TUI spreads scans across refreshes.
| Probe a new local server API | `llm.py` `ServerProber` | GET only, short timeouts, the process's own ports |
| Support an app that reads and closes its model | `handy.py` as the template | Read-only settings plus a bounded, mtime-cached log tail; never read transcription content. Generalize into data-driven adapters once a second app needs one |
| Add a GPU vendor or backend | `dxgi.py`, `collector.py`, a new module | Pair devices by LUID or PCI bus ID, never by name or index; load vendor DLLs by absolute system path |
-| Add a column or JSON field | `report.py` and `app.py` | Follow the null rules above; update the README tables |
+| Add a column or JSON field | `report.py` and `app.py` | Follow the null rules above; update the README tables. If it is a measured byte count, consider adding it to `diff.py` `MEASURED` |
+| Change snapshot comparison | `diff.py` | Works only on saved `--json` files, never live state. Compare measured fields directly; keep runtime-reported and estimated values in their own sections; an absent row is `not listed`, not zero |
| Change WSL matching | `wslhost.py` `ContextTracker` | Keep `tests/test_wslhost.py` replays passing; they are measured sequences |
## Verify
@@ -91,6 +93,7 @@ uv run --locked gputaskman --json
Windows `.venv`. The project needs Python 3.11+, which uv downloads if the distro's is older.
- Live checks: run a bounded, known workload (for example a llama-server with a model you have, or
a fixed-size CUDA allocation), then compare `--json` against Task Manager or `nvidia-smi`.
+ `gputaskman diff before.json after.json` shows exactly which measured bucket moved.
Record hardware, driver, and results in the PR.
- Screenshots: `tools/capture_screenshots.py` strips command lines and full paths, but review model
and process names before publishing.
diff --git a/README.md b/README.md
index 0febc78..44fdbf1 100644
--- a/README.md
+++ b/README.md
@@ -243,6 +243,7 @@ uv run --locked gtm # shorter alias
uv run --locked gputaskman -i 2 # sample every two seconds
uv run --locked gputaskman --once # one text snapshot
uv run --locked gputaskman --json # one JSON snapshot; implies --once
+uv run --locked gputaskman diff before.json after.json # compare two --json snapshots
uv run --locked gputaskman --no-host # WSL: don't read Windows host counters through interop
uv run --locked gputaskman --help
```
@@ -294,6 +295,35 @@ driver did not expose that reading; it does not by itself indicate a hardware fa
Missing per-process memory or engine samples likewise show `N/A`/`null`; the paged estimate is
unavailable when any of its input counters is missing.
+### Comparing snapshots
+
+To see which memory bucket actually grew when you load a model or change the context length, save
+a JSON snapshot before and after and compare them:
+
+```powershell
+uv run --locked gputaskman --json > before.json
+# load the model, or restart the server with a different -c, then send it one request
+uv run --locked gputaskman --json > after.json
+uv run --locked gputaskman diff before.json after.json # add --json for machine-readable output
+```
+
+The device and process tables compare **measured** counters only. Runtime-reported segments
+(llama.cpp buffer logs) and estimates (KV cache from GGUF metadata and `-c`) are listed separately
+under each process and are never added to measured totals. A model file that appears in a process
+is listed as evidence that the process opened or named it, not as GPU growth.
+
+Processes are paired by PID, then by name and listening ports, then by a unique name, because a
+model reload often restarts the server under a new PID. A process missing from one snapshot shows
+`not listed`, not zero: it was not running or used too little GPU to be listed. Processes that
+moved by less than 16 MB are hidden from the text output but included in `--json`.
+
+Take the "after" snapshot once the model has answered one request: CUDA and Vulkan can allocate
+lazily, and allocators keep freed memory cached, so shrinkage may appear late. On an RTX 4080 SUPER
+with Docker Model Runner's llama-server (Vulkan) and gemma-3-270m, changing `-c 4096` to `-c 32768`
+estimated +504 MB of KV cache, but the server's measured dedicated memory grew by only +83 MB.
+Gemma 3 uses sliding-window attention, so the estimate is an upper bound. The comparison makes
+that gap visible instead of hiding it.
+
## How can it know what's inside?
It combines evidence rather than reading arbitrary GPU memory. Windows' graphics kernel supplies
@@ -566,6 +596,7 @@ downloads are bundled in this repository.
| `llm.py` | Buffer logs, local server probing, and breakdowns |
| `collector.py` | Shared snapshot collection |
| `app.py` / `report.py` / `cli.py` | TUI, text/JSON, and command-line entry points |
+| `diff.py` | Before/after comparison of two `--json` snapshots |
## Next
diff --git a/src/gputaskman/cli.py b/src/gputaskman/cli.py
index 182691d..80a3340 100644
--- a/src/gputaskman/cli.py
+++ b/src/gputaskman/cli.py
@@ -8,8 +8,30 @@ import sys
import time
+def diff_main(argv: list[str]) -> None:
+ import json
+
+ ap = argparse.ArgumentParser(prog="gputaskman diff",
+ description="Compare two --json snapshots, for example before and after loading a model.")
+ ap.add_argument("before", help="earlier --json snapshot")
+ ap.add_argument("after", help="later --json snapshot")
+ ap.add_argument("--json", action="store_true", help="print the comparison as JSON")
+ args = ap.parse_args(argv)
+
+ from .diff import diff, load, to_text
+
+ try:
+ result = diff(load(args.before), load(args.after))
+ except (OSError, ValueError) as error:
+ ap.error(str(error))
+ print(json.dumps(result, indent=2) if args.json else to_text(result))
+
+
def main() -> None:
- ap = argparse.ArgumentParser(prog="gputaskman", description="What's inside your GPU: per-process VRAM, engines, and LLM weights/KV-cache breakdown.")
+ if len(sys.argv) > 1 and sys.argv[1] == "diff":
+ return diff_main(sys.argv[2:])
+ ap = argparse.ArgumentParser(prog="gputaskman", description="What's inside your GPU: per-process VRAM, engines, and LLM weights/KV-cache breakdown.",
+ epilog="gputaskman diff BEFORE.json AFTER.json compares two --json snapshots.")
ap.add_argument("--once", action="store_true", help="print one snapshot and exit (no TUI)")
ap.add_argument("--json", action="store_true", help="print one JSON snapshot and exit (implies --once)")
ap.add_argument("--gpu", type=int, default=0, help="GPU index (default 0)")
diff --git a/src/gputaskman/diff.py b/src/gputaskman/diff.py
new file mode 100644
index 0000000..31892f3
--- /dev/null
+++ b/src/gputaskman/diff.py
@@ -0,0 +1,253 @@
+"""Compare two `--json` snapshots: which measured memory buckets changed, next to what runtimes reported.
+
+Measured counters are compared on their own. Runtime-reported and estimated breakdowns are listed
+beside them, never added to measured totals. A model file appearing in a process is evidence that
+the process has the file, not that it is resident in GPU memory.
+"""
+
+from __future__ import annotations
+
+import json
+
+from .llm import gb
+
+MiB = 1 << 20
+NOISE = 16 * MiB # smaller per-process moves are allocator and compositor churn, not a model loading
+MEASURED = ("vram_bytes", "shared_bytes", "committed_bytes", "paged_out_bytes")
+DEVICE = (("vram_used", "dedicated used"), ("shared_used", "shared used"),
+ ("attributed", "attributed to processes"), ("unattributed", "unattributed"))
+SEGMENT_ORDER = ("weights", "kv", "compute", "runtime", "unknown")
+
+
+def load(path: str) -> dict:
+ with open(path, "rb") as f:
+ raw = f.read()
+ # Windows PowerShell 5.1 redirects (`>`) as UTF-16; PowerShell 7 and other shells write UTF-8.
+ text = raw.decode("utf-16") if raw[:2] in (b"\xff\xfe", b"\xfe\xff") else raw.decode("utf-8-sig")
+ data = json.loads(text)
+ if not isinstance(data, dict) or not isinstance(data.get("processes"), list):
+ raise ValueError(f"{path} is not a gputaskman --json snapshot")
+ return data
+
+
+def change(before, after) -> dict:
+ return {"before": before, "after": after,
+ "delta": after - before if before is not None and after is not None else None}
+
+
+def _get(d: dict | None, key: str):
+ return d.get(key) if d else None
+
+
+def _unattributed(s: dict):
+ used, attributed = s.get("vram_used"), s.get("attributed")
+ return used - attributed if used is not None and attributed is not None else None
+
+
+PLACEHOLDER_NAMES = ("?", "(outside this container)") # no identity: never pair these by name
+
+
+def _named(p: dict) -> bool:
+ return p.get("host") != "outside" and p.get("name") not in PLACEHOLDER_NAMES
+
+
+def match(before: list[dict], after: list[dict]) -> list[tuple[dict | None, dict | None, str]]:
+ """Pair rows by PID, then by name and ports, then by name, when each pairing is unambiguous.
+
+ A model reload often restarts the server under a new PID. WSL host rows have their own PID space.
+ Every row comes back exactly once: paired, new, or gone.
+ """
+ keys = [(p.get("host"), p.get("pid")) for p in before]
+ unique = {k for k in keys if k[1] is not None and keys.count(k) == 1}
+ left = dict(enumerate(before))
+ by_pid = {k: i for i, k in enumerate(keys) if k in unique}
+ pairs: list[tuple[dict | None, dict | None, str]] = []
+ rest: list[dict] = []
+ for a in after:
+ i = by_pid.get((a.get("host"), a.get("pid")))
+ if i is not None and i in left and left[i].get("name") == a.get("name"):
+ pairs.append((left.pop(i), a, "pid"))
+ else:
+ rest.append(a)
+
+ def ports(p: dict):
+ return (p.get("host"), p.get("name"), tuple(sorted(p["ports"]))) if p.get("ports") and _named(p) else None
+
+ def name(p: dict):
+ return (p.get("host"), p.get("name")) if _named(p) else None
+
+ for how, key in (("name+ports", ports), ("name", name)):
+ olds: dict = {}
+ news: dict = {}
+ for i, b in left.items():
+ olds.setdefault(key(b), []).append(i)
+ for a in rest:
+ news.setdefault(key(a), []).append(a)
+ for k, found in news.items():
+ if k is not None and len(found) == 1 and len(olds.get(k, [])) == 1:
+ pairs.append((left.pop(olds[k][0]), found[0], how))
+ rest.remove(found[0])
+ pairs += [(None, a, "new") for a in rest]
+ pairs += [(b, None, "gone") for b in left.values()]
+ return pairs
+
+
+def _segments(p: dict | None) -> tuple[dict, dict]:
+ sums: dict[str, int] = {}
+ exact: dict[str, bool] = {}
+ for s in (_get(p, "llm") or {}).get("segments") or []:
+ k = s.get("kind") or "unknown"
+ sums[k] = sums.get(k, 0) + int(s.get("bytes") or 0)
+ exact[k] = exact.get(k, True) and bool(s.get("exact"))
+ return sums, exact
+
+
+def _runtime(b: dict | None, a: dict | None) -> dict | None:
+ lb, la = _get(b, "llm"), _get(a, "llm")
+ if not lb and not la:
+ return None
+ sb, eb = _segments(b)
+ sa, ea = _segments(a)
+ kinds = sorted(set(sb) | set(sa), key=lambda k: SEGMENT_ORDER.index(k) if k in SEGMENT_ORDER else 99)
+ return {
+ "n_ctx": change(_get(lb, "n_ctx"), _get(la, "n_ctx")),
+ "segments": {k: {**change(sb.get(k), sa.get(k)),
+ "source": "runtime-reported" if eb.get(k, True) and ea.get(k, True) else "estimated"}
+ for k in kinds},
+ }
+
+
+def _files(b: dict | None, a: dict | None) -> dict:
+ fb = {m.get("path"): m for m in _get(b, "model_files") or []}
+ fa = {m.get("path"): m for m in _get(a, "model_files") or []}
+ return {"added": [{"path": p, "sources": m.get("sources")} for p, m in fa.items() if p not in fb],
+ "removed": [{"path": p, "sources": m.get("sources")} for p, m in fb.items() if p not in fa]}
+
+
+def _proc(b: dict | None, a: dict | None, how: str) -> dict:
+ p = a or b or {}
+ return {
+ "name": p.get("name"), "host": p.get("host"), "match": how,
+ "pid_before": _get(b, "pid"), "pid_after": _get(a, "pid"),
+ "measured": {k: change(_get(b, k), _get(a, k)) for k in MEASURED},
+ "inferred": {"vram_inferred_bytes": change(_get(b, "vram_inferred_bytes"), _get(a, "vram_inferred_bytes"))},
+ "runtime": _runtime(b, a),
+ "model_files": _files(b, a),
+ }
+
+
+def _size(p: dict) -> int:
+ v = p["measured"]["vram_bytes"]
+ if v["delta"] is not None:
+ return abs(v["delta"])
+ return v["after"] if v["after"] is not None else v["before"] or 0
+
+
+def diff(before: dict, after: dict) -> dict:
+ if before.get("gpu") != after.get("gpu") or before.get("backend") != after.get("backend"):
+ raise ValueError(f"snapshots are from different GPUs or backends: "
+ f"{before.get('gpu')} ({before.get('backend')}) vs {after.get('gpu')} ({after.get('backend')})")
+ device = {k: change(before.get(k), after.get(k)) for k, _ in DEVICE if k != "unattributed"}
+ device["unattributed"] = change(_unattributed(before), _unattributed(after))
+ procs = [_proc(b, a, how) for b, a, how in match(before["processes"], after["processes"])]
+ procs.sort(key=_size, reverse=True)
+ taken_b, taken_a = before.get("taken"), after.get("taken")
+ seconds = round(taken_a - taken_b, 1) if isinstance(taken_b, (int, float)) and isinstance(taken_a, (int, float)) else None
+ return {"gpu": after.get("gpu"), "backend": after.get("backend"), "seconds": seconds,
+ "device": device, "processes": procs}
+
+
+# ---------------------------------------------------------------- text
+
+
+def _gb(v) -> str:
+ return "N/A" if v is None else gb(v)
+
+
+def _signed(v) -> str:
+ if v is None:
+ return "N/A"
+ if abs(v) < MiB // 2:
+ return "0 MB"
+ return ("+" if v >= 0 else "-") + gb(abs(v))
+
+
+def _moved(c: dict) -> bool:
+ """A value appeared, disappeared, or moved by at least the noise threshold."""
+ if c["before"] == c["after"]:
+ return False
+ return c["delta"] is None or abs(c["delta"]) >= NOISE
+
+
+def _changed(p: dict) -> bool:
+ if p["match"] in ("new", "gone"):
+ return True
+ if any(abs(c["delta"] or 0) >= NOISE for c in p["measured"].values()):
+ return True
+ if abs(p["inferred"]["vram_inferred_bytes"]["delta"] or 0) >= NOISE:
+ return True
+ r = p["runtime"]
+ # Remainder segments follow the measured total, so they move with every sample; apply the same threshold.
+ if r and (r["n_ctx"]["before"] != r["n_ctx"]["after"] or any(_moved(s) for s in r["segments"].values())):
+ return True
+ return bool(p["model_files"]["added"] or p["model_files"]["removed"])
+
+
+def _pid(p: dict) -> str:
+ b, a = p["pid_before"], p["pid_after"]
+ pid = str(a if b is None else b if a is None or a == b else f"{b}->{a}")
+ return f"{'W' if p['host'] == 'windows' else 'H'}:{pid}" if p["host"] else pid
+
+
+def to_text(d: dict) -> str:
+ when = f", {d['seconds']} s apart" if d["seconds"] is not None else ""
+ out = [f"gputaskman diff: {d['gpu'] or 'unknown GPU'} ({d['backend']}){when}",
+ "Measured counters are compared directly. Runtime-reported and estimated values are listed",
+ "separately and are not added to measured totals.", "",
+ f"{'DEVICE (measured)':<26}{'BEFORE':>11}{'AFTER':>11}{'CHANGE':>11}"]
+ for key, label in DEVICE:
+ c = d["device"][key]
+ out.append(f"{label:<26}{_gb(c['before']):>11}{_gb(c['after']):>11}{_signed(c['delta']):>11}")
+
+ procs = [p for p in d["processes"] if _changed(p)]
+ out += ["", f"{'PROCESSES (dedicated)':<22}{'PID':>14} {'MATCH':<11}{'BEFORE':>11}{'AFTER':>11}"
+ f"{'CHANGE':>11}{'SHARED +/-':>11}"]
+ for p in procs:
+ v, s = p["measured"]["vram_bytes"], p["measured"]["shared_bytes"]
+ before = "not listed" if p["match"] == "new" else _gb(v["before"])
+ after = "not listed" if p["match"] == "gone" else _gb(v["after"])
+ out.append(f"{(p['name'] or '?')[:21]:<22}{_pid(p):>14} {p['match']:<11}{before:>11}{after:>11}"
+ f"{_signed(v['delta']):>11}{_signed(s['delta']):>11}")
+ if not procs:
+ out.append("(no process changed by 16 MB or more)")
+ if len(procs) < len(d["processes"]):
+ out.append(f"{len(d['processes']) - len(procs)} process(es) changed by less than 16 MB are not shown; "
+ "--json lists all.")
+
+ for p in procs:
+ detail = []
+ inf = p["inferred"]["vram_inferred_bytes"]
+ if _moved(inf):
+ detail.append(f" inferred VRAM (WSL context match) {_gb(inf['before'])} -> {_gb(inf['after'])}"
+ f" {_signed(inf['delta'])}")
+ r = p["runtime"]
+ if r:
+ n = r["n_ctx"]
+ if n["before"] != n["after"]:
+ detail.append(f" context length {n['before'] if n['before'] is not None else 'N/A'} -> "
+ f"{n['after'] if n['after'] is not None else 'N/A'}")
+ for kind, s in r["segments"].items():
+ if _moved(s):
+ detail.append(f" {kind:<8} {_gb(s['before']):>9} -> {_gb(s['after']):>9}"
+ f" {_signed(s['delta']):>9} {s['source']}")
+ for verb, key in (("added", "added"), ("removed", "removed")):
+ for f in p["model_files"][key]:
+ detail.append(f" model file {verb}: {f['path']} [{', '.join(f['sources'] or [])}]")
+ if detail:
+ out += ["", f"{p['name']} ({_pid(p)})"] + detail
+ if any(p["model_files"]["added"] or p["model_files"]["removed"] for p in procs):
+ out += ["", "Model files show what a process opened or named, not what is resident in GPU memory."]
+ if any(p["match"] in ("new", "gone") for p in procs):
+ out.append("'not listed' means the process was absent from that snapshot: not running, or using too "
+ "little GPU to be listed.")
+ return "\n".join(out)
diff --git a/tests/test_diff.py b/tests/test_diff.py
new file mode 100644
index 0000000..b9dbabe
--- /dev/null
+++ b/tests/test_diff.py
@@ -0,0 +1,153 @@
+from __future__ import annotations
+
+import contextlib
+import io
+import json
+import os
+import tempfile
+import unittest
+from unittest.mock import patch
+
+from gputaskman.cli import main
+from gputaskman.diff import diff, load, match, to_text
+
+GiB = 1 << 30
+MiB = 1 << 20
+
+
+def proc(pid, name, vram=None, shared=0, host=None, ports=(), llm=None, files=(), inferred=None):
+ return {"pid": pid, "host": host, "name": name, "vram_bytes": vram, "shared_bytes": shared,
+ "committed_bytes": None, "paged_out_bytes": None, "vram_inferred_bytes": inferred,
+ "ports": list(ports), "model_files": [{"path": f, "sources": ["mapped"]} for f in files],
+ **({"llm": llm} if llm else {})}
+
+
+def snap(procs, used, attributed, taken=100.0, gpu="RTX", backend="wddm"):
+ return {"taken": taken, "gpu": gpu, "backend": backend, "vram_used": used, "shared_used": 0,
+ "attributed": attributed, "processes": procs}
+
+
+def llm(n_ctx, kv, exact=False):
+ return {"n_ctx": n_ctx, "segments": [{"label": "weights", "bytes": 4 * GiB, "kind": "weights", "exact": exact},
+ {"label": "KV", "bytes": kv, "kind": "kv", "exact": exact}]}
+
+
+class MatchTests(unittest.TestCase):
+ def test_pid_then_name_and_ports_then_unique_name(self):
+ before = [proc(1, "a.exe"), proc(2, "llama-server", ports=[8080]), proc(3, "solo.exe")]
+ after = [proc(1, "a.exe"), proc(20, "llama-server", ports=[8080]), proc(30, "solo.exe")]
+ self.assertEqual([(b["pid"], a["pid"], how) for b, a, how in match(before, after)],
+ [(1, 1, "pid"), (2, 20, "name+ports"), (3, 30, "name")])
+
+ def test_reused_pid_ambiguous_names_and_host_pid_space_are_not_paired(self):
+ before = [proc(5, "old.exe"), proc(7, "w.exe"), proc(8, "w.exe"), proc(9, "x", host="windows")]
+ after = [proc(5, "new.exe"), proc(17, "w.exe"), proc(18, "w.exe"), proc(9, "x")]
+ result = {(b and b["pid"], a and a["pid"], how) for b, a, how in match(before, after)}
+ self.assertEqual(result, {(None, 5, "new"), (None, 17, "new"), (None, 18, "new"), (None, 9, "new"),
+ (5, None, "gone"), (7, None, "gone"), (8, None, "gone"), (9, None, "gone")})
+
+ def test_placeholder_rows_and_missing_pids_are_never_paired_or_dropped(self):
+ before = [proc(7, "(outside this container)", host="outside"), proc(None, "a"), proc(None, "b"),
+ proc(40, "?", host="windows")]
+ after = [proc(9, "(outside this container)", host="outside"), proc(None, "a"), proc(41, "?", host="windows")]
+ result = sorted(((b and b["name"], a and a["name"], how) for b, a, how in match(before, after)), key=str)
+ self.assertEqual(result, sorted([("(outside this container)", None, "gone"), (None, "(outside this container)", "new"),
+ ("?", None, "gone"), (None, "?", "new"), ("a", "a", "name"),
+ ("b", None, "gone")], key=str))
+ d = diff(snap(before, 0, 0), snap(after, 0, 0))
+ self.assertIn("H:9", to_text(d))
+ self.assertIn("W:41", to_text(d))
+
+
+class DiffTests(unittest.TestCase):
+ def test_measured_runtime_and_mapped_evidence_stay_separate(self):
+ before = snap([proc(1, "dwm.exe", vram=2 * GiB),
+ proc(2, "llama-server", vram=5 * GiB, ports=[8080], llm=llm(4096, GiB // 2))],
+ used=8 * GiB, attributed=7 * GiB)
+ after = snap([proc(1, "dwm.exe", vram=2 * GiB),
+ proc(22, "llama-server", vram=9 * GiB, ports=[8080], llm=llm(32768, 4 * GiB),
+ files=[r"D:\models\q.gguf"]),
+ proc(3, "python.exe", vram=GiB)],
+ used=13 * GiB, attributed=12 * GiB, taken=142.5)
+ d = diff(before, after)
+ self.assertEqual(d["seconds"], 42.5)
+ self.assertEqual(d["device"]["vram_used"]["delta"], 5 * GiB)
+ self.assertEqual(d["device"]["unattributed"], {"before": GiB, "after": GiB, "delta": 0})
+ server, new, dwm = d["processes"]
+ self.assertEqual((server["match"], server["measured"]["vram_bytes"]["delta"]), ("name+ports", 4 * GiB))
+ self.assertEqual(server["runtime"]["n_ctx"], {"before": 4096, "after": 32768, "delta": 28672})
+ self.assertEqual(server["runtime"]["segments"]["kv"]["delta"], 3584 * MiB)
+ self.assertEqual(server["runtime"]["segments"]["kv"]["source"], "estimated")
+ self.assertEqual(server["model_files"]["added"], [{"path": r"D:\models\q.gguf", "sources": ["mapped"]}])
+ self.assertEqual(new["match"], "new")
+ self.assertEqual(new["measured"]["vram_bytes"], {"before": None, "after": GiB, "delta": None})
+
+ text = to_text(d)
+ self.assertIn("2->22", text)
+ self.assertIn("context length 4096 -> 32768", text)
+ self.assertIn("+3.50 GB estimated", text)
+ self.assertIn("not listed", text)
+ self.assertIn("not what is resident in GPU memory", text)
+ self.assertNotIn("dwm.exe", text)
+ self.assertIn("1 process(es) changed by less than 16 MB", text)
+
+ def test_runtime_reported_segments_and_unknown_measurements(self):
+ before = snap([proc(1, "llama", vram=None, llm=llm(4096, GiB, exact=True))], used=None, attributed=None)
+ after = snap([proc(1, "llama", vram=None, llm=llm(8192, 2 * GiB, exact=True))], used=None, attributed=None)
+ d = diff(before, after)
+ self.assertEqual(d["device"]["unattributed"]["delta"], None)
+ self.assertEqual(d["processes"][0]["measured"]["vram_bytes"]["delta"], None)
+ self.assertEqual(d["processes"][0]["runtime"]["segments"]["kv"]["source"], "runtime-reported")
+ self.assertIn("N/A", to_text(d))
+
+ def test_rejects_snapshots_from_different_gpus(self):
+ with self.assertRaisesRegex(ValueError, "different GPUs"):
+ diff(snap([], 0, 0, gpu="A"), snap([], 0, 0, gpu="B"))
+
+ def test_remainder_segments_follow_the_noise_threshold(self):
+ def server(runtime):
+ view = {"n_ctx": 4096, "segments": [{"label": "rest", "bytes": runtime, "kind": "runtime", "exact": False}]}
+ return proc(1, "llama", vram=GiB + runtime, llm=view)
+ d = diff(snap([server(GiB)], 3 * GiB, 2 * GiB), snap([server(GiB + 4096)], 3 * GiB, 2 * GiB))
+ self.assertIn("(no process changed by 16 MB or more)", to_text(d))
+ self.assertNotIn("llama (1)", to_text(d))
+
+
+class LoadAndCliTests(unittest.TestCase):
+ def setUp(self):
+ self.dir = tempfile.TemporaryDirectory()
+ self.addCleanup(self.dir.cleanup)
+
+ def write(self, name, data, encoding):
+ path = os.path.join(self.dir.name, name)
+ with open(path, "w", encoding=encoding) as f:
+ f.write(json.dumps(data))
+ return path
+
+ def test_reads_powershell_utf16_and_utf8_bom(self):
+ data = snap([proc(1, "a", vram=MiB)], used=MiB, attributed=MiB)
+ self.assertEqual(load(self.write("a.json", data, "utf-16")), data)
+ self.assertEqual(load(self.write("b.json", data, "utf-8-sig")), data)
+ with self.assertRaisesRegex(ValueError, "not a gputaskman --json snapshot"):
+ load(self.write("c.json", {"hello": 1}, "utf-8"))
+
+ def test_cli_text_json_and_errors(self):
+ a = self.write("a.json", snap([], used=GiB, attributed=GiB), "utf-8")
+ b = self.write("b.json", snap([proc(1, "x", vram=GiB)], used=2 * GiB, attributed=2 * GiB), "utf-8")
+ out = io.StringIO()
+ with patch("sys.argv", ["gputaskman", "diff", a, b]), contextlib.redirect_stdout(out):
+ main()
+ self.assertIn("dedicated used", out.getvalue())
+ out = io.StringIO()
+ with patch("sys.argv", ["gputaskman", "diff", a, b, "--json"]), contextlib.redirect_stdout(out):
+ main()
+ self.assertEqual(json.loads(out.getvalue())["device"]["vram_used"]["delta"], GiB)
+ err = io.StringIO()
+ with patch("sys.argv", ["gputaskman", "diff", a, os.path.join(self.dir.name, "missing.json")]), \
+ contextlib.redirect_stderr(err), self.assertRaises(SystemExit):
+ main()
+ self.assertIn("missing.json", err.getvalue())
+
+
+if __name__ == "__main__":
+ unittest.main()