v0.2.0 — CUDA env diagnostics & KV-cache OOM rule

v0.2.0

Diagnostics release since v0.1.0. New rules for CUDA 13 / GB10 (SM_121) environment mismatches and vLLM KV-cache allocation failures that were easy to misread as host memory pressure.

What's new

CUDA environment diagnostics

• Collector for driver CUDA version, nvcc, PyTorch CUDA build, and linked libcudart
• New rules:
  • cuda.wheel_mismatch — PyTorch (or other) wheel built for a CUDA major that does not match the driver
  • cuda.libcudart_missing — package linked against a CUDA runtime that is not installed
  • cuda.sm121_not_in_arch_list — PyTorch build ships no SM_121 kernels for GB10
  • cuda.nvcc_toolkit_mismatch — nvcc on PATH is older than the driver's CUDA version

vLLM KV-cache OOM (backend.kv_cache_oom)

• Detects vLLM's No available memory for the cache blocks (log-based; use --include-logs)
• Distinct from memory.uma_pressure — GPU KV / CUDA-graph budget, not host RAM/PSI
• Recommends --enforce-eager, raising utilization when safe, or lowering max context — not “quantize smaller” as the primary fix

Install / upgrade

pip install -U git+https://github.com/joeynyc/spark-doctor.git@v0.2.0
# or from a clone of main:
pip install -e .

spark-doctor version   # → spark-doctor 0.2.0
spark-doctor self-test

Notes

• KV-cache OOM currently requires a scan with --include-logs (host journal/dmesg). Container-only stdout (default Docker json-file) is a known gap for a later release.
• Full suite: 39 tests passing.