gpucheck-cli 0.1.0__tar.gz

gpucheck_cli-0.1.0/LICENSE

@@ -0,0 +1,177 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS

gpucheck_cli-0.1.0/PKG-INFO

@@ -0,0 +1,122 @@
+Metadata-Version: 2.4
+Name: gpucheck-cli
+Version: 0.1.0
+Summary: Open-source CLI that health-checks NVIDIA GPUs
+Author: narekkeshishyan
+Author-email: narekkeshishyan <keshishyan01@gmail.com>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Requires-Dist: pynvml
+Requires-Dist: torch ; extra == 'load'
+Requires-Python: >=3.10
+Project-URL: Homepage, https://gpucheck.dev
+Project-URL: Repository, https://github.com/narek-keshishyan/gpucheck
+Provides-Extra: load
+Description-Content-Type: text/markdown
+
+# gpucheck
+
+One command that stress-tests an NVIDIA GPU and tells you whether it is healthy, throttling, or degraded.
+
+Website: [gpucheck.dev](https://gpucheck.dev) — includes the optional $29 signed certificate for used-GPU listings.
+
+It records a short idle baseline, runs a sustained matrix-multiply load, and samples temperature, clocks, power, and throttle reasons the whole time. It then explains what it saw in plain language: thermal throttling, power-limit throttling, memory problems, or throughput well below what that model should deliver.
+
+## Install
+
+```
+uvx --from "gpucheck-cli[load]" gpucheck --quick
+# or
+pip install "gpucheck-cli[load]"
+```
+
+The load generator needs PyTorch with CUDA. It is an optional extra (`[load]`) because torch is large; if you already have a CUDA build of torch installed, plain `pip install gpucheck-cli` is enough. (The PyPI package is `gpucheck-cli`; the installed command is `gpucheck`.) Without torch/CUDA the tool still runs but generates no load (it prints a warning), so performance metrics are left blank.
+
+## Usage
+
+```
+gpucheck                 # standard run: 60 s baseline, 10 min load
+gpucheck --quick         # 30 s baseline, 150 s load
+gpucheck --long          # 60 s baseline, 30 min load
+gpucheck --offline       # never contacts a server
+gpucheck --dry-run       # print exactly what would be uploaded, upload nothing
+gpucheck --yes-upload    # upload without the prompt
+gpucheck --server URL    # upload server (http or https); default https://gpucheck-api.fly.dev
+gpucheck --json PATH     # where to write result.json (default ./gpucheck-result.json)
+gpucheck --certify       # use a one-time server challenge so the result can earn a certificate
+```
+
+The result is always written locally to `result.json` first. The tool only reads from the GPU; it does not change any settings. Ctrl-C stops a run at any time; an interrupted run writes no result.json and uploads nothing.
+
+### Upload flow
+
+After a run, unless you passed `--offline`, gpucheck asks whether to upload (to `https://gpucheck-api.fly.dev` unless you pass `--server URL`). If you say yes you get a result page URL, a grade such as `Grade B — delivers 94.1% of a healthy <model> (n=12, low confidence)` (or the reason there is none, for example "insufficient reference (n=X)" while too few comparable runs exist, or "measurements only" for MIG), and a delete token. Save the token: it is the only way to delete the page later.
+
+```
+curl -X DELETE -H "X-Delete-Token: <token>" <server>/v1/runs/<run_id>
+```
+
+## What gets uploaded
+
+Nothing, unless you opt in. Uploading is off in non-interactive shells unless you pass `--yes-upload`. `--dry-run` prints the exact payload so you can read it first.
+
+The payload is the contents of `result.json`: GPU model and driver details, measurements, findings, and the time series of samples. The GPU identifier is replaced by a salted-hash UUID, so the raw serial is never sent. The salt is a public constant in this source code, so anyone who already knows your GPU's UUID can recompute the hash and recognise your card.
+
+Result pages are public to anyone with the link, and the server also serves back the full uploaded JSON (every field above, including the sample time series) at `/v1/runs/<run_id>`. The run ID is derived from the content, and the server returns a delete token (stored only as a hash) that lets you remove your page.
+
+## Certificates (`--certify`)
+
+`gpucheck --certify` asks the server for a one-time challenge, runs the workload the server prescribes (a set of matrix sizes and an execution order) instead of the default one, and uploads the result with the challenge attached. If the run qualifies, the result page offers a signed certificate for it. Certifying a run is a separate purchase, made on the result page.
+
+What you need:
+
+- A server that has certification turned on. The default server is `https://gpucheck-api.fly.dev`; pass `--server URL` for another one. If the challenge cannot be fetched (the server has certification turned off, or cannot be reached), gpucheck stops before the run with a message and exit code 1.
+- Working PyTorch with CUDA. Without it, `--certify` stops with exit code 1 instead of falling back to a run with no load.
+- The normal upload prompt still applies. A certificate can only be made from an uploaded result, so answer yes, or pass `--yes-upload` in a script.
+
+`--certify` cannot be combined with `--offline`, `--dry-run`, or `--quick`; the argument parser rejects the combination at startup. Certificates need a full-length run (at least 600 s of load), so a quick run could never earn one.
+
+If the challenge expires before the run finishes (challenges are valid for 2 hours), gpucheck prints one warning, `challenge expired before upload; run again to certify — result saved locally`, does not upload, and exits normally. The result is still written to the `--json` path.
+
+Fake mode: `--fake` with `--certify` runs mechanically, but a real server rejects it with "upload arrived too soon after challenge", because the simulated run finishes instantly. This is intended: fakes cannot earn certificates.
+
+After a `--certify` upload, gpucheck prints the server's verdict: `Certifiable: yes`, or `Not certifiable: <reason>` with the reason the server gave (`certify_note`). If the server refuses to certify a run, the upload still succeeds and the result is still stored; the run simply gets no purchase button. A certifiable run also needs a grade, a complete (not aborted, not quarantined) load phase, and a card identity before the result page offers a certificate.
+
+### What a certificate proves
+
+A certificate raises the cost of lying about a GPU. It is not proof of anything on its own.
+
+- The run used a fresh one-time server challenge and could not be uploaded before the full run time had passed. The uploaded result echoes the challenge's workload parameters, but the server cannot see whether that workload actually ran.
+- The signed payload binds that certificate to one stored result (by its SHA-256), one card (its salted-hash identifier, the same one in the uploaded result), one grade, and one run.
+- Certificates issued while the server is in payment test mode carry a TEST banner and `livemode: false` in the signed payload. They are not real purchases.
+
+### What a certificate does not prove
+
+- It does not show that the card is healthy or will stay healthy. A single run is a snapshot, as described under Limitations.
+- It does not stop someone who controls the machine. Someone with full control can fabricate telemetry that matches the prescribed workload and timing. The server cannot see the hardware directly.
+- It does not stop re-running. A card owner can keep running until a run looks good and then buy a certificate for that one. When a newer certificate is issued for the same card, the older one is marked as superseded, which makes this visible, but it is not prevented.
+- Revocation is not part of the signature. A revoked certificate still verifies offline; only the live verify endpoint knows about revocation.
+
+Verifying a certificate offline needs the certificate payload, its signature, and the public key from `/v1/pubkey`. The exact steps and a one-line Python check are on the server's `/verify` page and in the server's README.
+
+## Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| 0 | Run completed |
+| 1 | Preflight refused to run (for example the GPU is busy) |
+| 2 | No NVIDIA GPU or driver available |
+| 3 | Run aborted partway (thermal limit, ECC errors, or lost telemetry); result.json is still written |
+
+## Limitations
+
+- NVIDIA GPUs on Linux only.
+- MIG instances give measurements only; they are not graded.
+- Needs PyTorch with CUDA to generate load; without it, performance numbers are blank.
+- It refuses to run on a GPU that is already busy.
+- Grades depend on a reference set of comparable runs; for new or rare models you will see "insufficient reference".
+- A single run is a snapshot. A healthy result does not guarantee the card will never fail.
+
+## License
+
+Apache-2.0

gpucheck_cli-0.1.0/README.md

@@ -0,0 +1,106 @@
+# gpucheck
+
+One command that stress-tests an NVIDIA GPU and tells you whether it is healthy, throttling, or degraded.
+
+Website: [gpucheck.dev](https://gpucheck.dev) — includes the optional $29 signed certificate for used-GPU listings.
+
+It records a short idle baseline, runs a sustained matrix-multiply load, and samples temperature, clocks, power, and throttle reasons the whole time. It then explains what it saw in plain language: thermal throttling, power-limit throttling, memory problems, or throughput well below what that model should deliver.
+
+## Install
+
+```
+uvx --from "gpucheck-cli[load]" gpucheck --quick
+# or
+pip install "gpucheck-cli[load]"
+```
+
+The load generator needs PyTorch with CUDA. It is an optional extra (`[load]`) because torch is large; if you already have a CUDA build of torch installed, plain `pip install gpucheck-cli` is enough. (The PyPI package is `gpucheck-cli`; the installed command is `gpucheck`.) Without torch/CUDA the tool still runs but generates no load (it prints a warning), so performance metrics are left blank.
+
+## Usage
+
+```
+gpucheck                 # standard run: 60 s baseline, 10 min load
+gpucheck --quick         # 30 s baseline, 150 s load
+gpucheck --long          # 60 s baseline, 30 min load
+gpucheck --offline       # never contacts a server
+gpucheck --dry-run       # print exactly what would be uploaded, upload nothing
+gpucheck --yes-upload    # upload without the prompt
+gpucheck --server URL    # upload server (http or https); default https://gpucheck-api.fly.dev
+gpucheck --json PATH     # where to write result.json (default ./gpucheck-result.json)
+gpucheck --certify       # use a one-time server challenge so the result can earn a certificate
+```
+
+The result is always written locally to `result.json` first. The tool only reads from the GPU; it does not change any settings. Ctrl-C stops a run at any time; an interrupted run writes no result.json and uploads nothing.
+
+### Upload flow
+
+After a run, unless you passed `--offline`, gpucheck asks whether to upload (to `https://gpucheck-api.fly.dev` unless you pass `--server URL`). If you say yes you get a result page URL, a grade such as `Grade B — delivers 94.1% of a healthy <model> (n=12, low confidence)` (or the reason there is none, for example "insufficient reference (n=X)" while too few comparable runs exist, or "measurements only" for MIG), and a delete token. Save the token: it is the only way to delete the page later.
+
+```
+curl -X DELETE -H "X-Delete-Token: <token>" <server>/v1/runs/<run_id>
+```
+
+## What gets uploaded
+
+Nothing, unless you opt in. Uploading is off in non-interactive shells unless you pass `--yes-upload`. `--dry-run` prints the exact payload so you can read it first.
+
+The payload is the contents of `result.json`: GPU model and driver details, measurements, findings, and the time series of samples. The GPU identifier is replaced by a salted-hash UUID, so the raw serial is never sent. The salt is a public constant in this source code, so anyone who already knows your GPU's UUID can recompute the hash and recognise your card.
+
+Result pages are public to anyone with the link, and the server also serves back the full uploaded JSON (every field above, including the sample time series) at `/v1/runs/<run_id>`. The run ID is derived from the content, and the server returns a delete token (stored only as a hash) that lets you remove your page.
+
+## Certificates (`--certify`)
+
+`gpucheck --certify` asks the server for a one-time challenge, runs the workload the server prescribes (a set of matrix sizes and an execution order) instead of the default one, and uploads the result with the challenge attached. If the run qualifies, the result page offers a signed certificate for it. Certifying a run is a separate purchase, made on the result page.
+
+What you need:
+
+- A server that has certification turned on. The default server is `https://gpucheck-api.fly.dev`; pass `--server URL` for another one. If the challenge cannot be fetched (the server has certification turned off, or cannot be reached), gpucheck stops before the run with a message and exit code 1.
+- Working PyTorch with CUDA. Without it, `--certify` stops with exit code 1 instead of falling back to a run with no load.
+- The normal upload prompt still applies. A certificate can only be made from an uploaded result, so answer yes, or pass `--yes-upload` in a script.
+
+`--certify` cannot be combined with `--offline`, `--dry-run`, or `--quick`; the argument parser rejects the combination at startup. Certificates need a full-length run (at least 600 s of load), so a quick run could never earn one.
+
+If the challenge expires before the run finishes (challenges are valid for 2 hours), gpucheck prints one warning, `challenge expired before upload; run again to certify — result saved locally`, does not upload, and exits normally. The result is still written to the `--json` path.
+
+Fake mode: `--fake` with `--certify` runs mechanically, but a real server rejects it with "upload arrived too soon after challenge", because the simulated run finishes instantly. This is intended: fakes cannot earn certificates.
+
+After a `--certify` upload, gpucheck prints the server's verdict: `Certifiable: yes`, or `Not certifiable: <reason>` with the reason the server gave (`certify_note`). If the server refuses to certify a run, the upload still succeeds and the result is still stored; the run simply gets no purchase button. A certifiable run also needs a grade, a complete (not aborted, not quarantined) load phase, and a card identity before the result page offers a certificate.
+
+### What a certificate proves
+
+A certificate raises the cost of lying about a GPU. It is not proof of anything on its own.
+
+- The run used a fresh one-time server challenge and could not be uploaded before the full run time had passed. The uploaded result echoes the challenge's workload parameters, but the server cannot see whether that workload actually ran.
+- The signed payload binds that certificate to one stored result (by its SHA-256), one card (its salted-hash identifier, the same one in the uploaded result), one grade, and one run.
+- Certificates issued while the server is in payment test mode carry a TEST banner and `livemode: false` in the signed payload. They are not real purchases.
+
+### What a certificate does not prove
+
+- It does not show that the card is healthy or will stay healthy. A single run is a snapshot, as described under Limitations.
+- It does not stop someone who controls the machine. Someone with full control can fabricate telemetry that matches the prescribed workload and timing. The server cannot see the hardware directly.
+- It does not stop re-running. A card owner can keep running until a run looks good and then buy a certificate for that one. When a newer certificate is issued for the same card, the older one is marked as superseded, which makes this visible, but it is not prevented.
+- Revocation is not part of the signature. A revoked certificate still verifies offline; only the live verify endpoint knows about revocation.
+
+Verifying a certificate offline needs the certificate payload, its signature, and the public key from `/v1/pubkey`. The exact steps and a one-line Python check are on the server's `/verify` page and in the server's README.
+
+## Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| 0 | Run completed |
+| 1 | Preflight refused to run (for example the GPU is busy) |
+| 2 | No NVIDIA GPU or driver available |
+| 3 | Run aborted partway (thermal limit, ECC errors, or lost telemetry); result.json is still written |
+
+## Limitations
+
+- NVIDIA GPUs on Linux only.
+- MIG instances give measurements only; they are not graded.
+- Needs PyTorch with CUDA to generate load; without it, performance numbers are blank.
+- It refuses to run on a GPU that is already busy.
+- Grades depend on a reference set of comparable runs; for new or rare models you will see "insufficient reference".
+- A single run is a snapshot. A healthy result does not guarantee the card will never fail.
+
+## License
+
+Apache-2.0

gpucheck_cli-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[project]
+name = "gpucheck-cli"
+version = "0.1.0"
+description = "Open-source CLI that health-checks NVIDIA GPUs"
+readme = "README.md"
+license = "Apache-2.0"
+license-files = ["LICENSE"]
+authors = [
+    { name = "narekkeshishyan", email = "keshishyan01@gmail.com" }
+]
+requires-python = ">=3.10"
+dependencies = ["pynvml"]
+
+[project.optional-dependencies]
+load = ["torch"]
+
+[project.urls]
+Homepage = "https://gpucheck.dev"
+Repository = "https://github.com/narek-keshishyan/gpucheck"
+
+[project.scripts]
+gpucheck = "gpucheck.cli:main"
+
+[dependency-groups]
+dev = ["pytest"]
+
+[build-system]
+requires = ["uv_build>=0.11.6,<0.12.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+# Distribution is gpucheck-cli (the bare name is taken on PyPI); import package stays gpucheck.
+module-name = "gpucheck"

gpucheck_cli-0.1.0/src/gpucheck/__init__.py

@@ -0,0 +1 @@
+"""gpucheck: health-check NVIDIA GPUs."""

gpucheck_cli-0.1.0/src/gpucheck/adapter.py

@@ -0,0 +1,192 @@
+"""Telemetry types and the adapter protocol, plus the real NVML adapter.
+
+All NVML access here is read-only: no NVML setter is ever called.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import time
+import warnings
+from dataclasses import dataclass
+from typing import Protocol
+
+
+class AdapterUnavailable(Exception):
+    """Raised when no GPU or NVIDIA driver is available."""
+
+
+@dataclass(frozen=True)
+class GpuInventory:
+    model_name: str
+    uuid_hash: str
+    driver: str
+    cuda: str | None
+    ecc_enabled: bool | None
+    power_limit_w: float | None
+    default_power_limit_w: float | None
+    mig_enabled: bool
+    fractional: bool
+    retired_pages: int | None
+    remapped_rows: int | None  # correctable + uncorrectable
+    row_remap_pending: bool | None = None
+    row_remap_failure: bool | None = None
+
+
+@dataclass(frozen=True)
+class TelemetrySample:
+    t_s: float
+    temp_c: float | None
+    power_w: float | None
+    sm_clock_mhz: float | None
+    fan_pct: float | None
+    throttle_reasons: frozenset[str] | None  # None = NVML could not report reasons (unknown)
+    ecc_volatile: int | None
+    achieved_tflops: float | None
+
+
+class TelemetryAdapter(Protocol):
+    def inventory(self) -> GpuInventory: ...
+
+    def sample(self) -> TelemetrySample: ...
+
+    def busy(self) -> bool | None: ...
+
+
+def hash_uuid(uuid: str) -> str:
+    return hashlib.sha256(("gpucheck.v1." + uuid).encode()).hexdigest()[:16]
+
+
+def _text(value: object) -> str:
+    return value.decode() if isinstance(value, bytes) else str(value)
+
+
+def _try(fn, *args):
+    """Call an NVML query; None if the GPU does not support it."""
+    try:
+        return fn(*args)
+    except Exception:
+        return None
+
+
+# NVML ABI values, used only when pynvml exposes neither naming family.
+_ABI = {
+    "SwPowerCap": 0x4,
+    "SwThermalSlowdown": 0x20,
+    "HwThermalSlowdown": 0x40,
+    "HwPowerBrakeSlowdown": 0x80,
+}
+
+
+def _const(nv, *names: str, default: int) -> int:
+    """First of `names` that pynvml defines, else `default`; never raises."""
+    for name in names:
+        value = getattr(nv, name, None)
+        if isinstance(value, int):
+            return value
+    return default
+
+
+def _reason_bit(nv, suffix: str) -> int:
+    # pynvml renamed "ClocksThrottleReason" to "ClocksEventReason" (NVML 12.x); the
+    # upper-case NVML_CLOCKS_THROTTLE_REASON_* spelling never existed in pynvml.
+    return _const(
+        nv,
+        f"nvmlClocksEventReason{suffix}",
+        f"nvmlClocksThrottleReason{suffix}",
+        default=_ABI[suffix],
+    )
+
+
+class NvmlAdapter(TelemetryAdapter):
+    """Reads GPU 0 through NVML (pynvml)."""
+
+    def __init__(self, index: int = 0) -> None:
+        try:
+            with warnings.catch_warnings():
+                warnings.simplefilter("ignore", FutureWarning)  # pynvml deprecation notice
+                import pynvml
+
+            pynvml.nvmlInit()
+            self._nv = pynvml
+            self._h = pynvml.nvmlDeviceGetHandleByIndex(index)
+        except Exception as exc:  # ImportError, NVMLError, missing library...
+            raise AdapterUnavailable(f"NVML unavailable: {exc}") from exc
+        self._t0 = time.monotonic()
+
+    def _q(self, name: str, *args):
+        """Optional NVML query by name: None if pynvml lacks it or the GPU does not support it."""
+        fn = getattr(self._nv, name, None)
+        return None if fn is None else _try(fn, *args)
+
+    def inventory(self) -> GpuInventory:
+        nv, h = self._nv, self._h
+        uuid = _text(nv.nvmlDeviceGetUUID(h))
+        cuda_raw = self._q("nvmlSystemGetCudaDriverVersion")
+        cuda = f"{cuda_raw // 1000}.{(cuda_raw % 1000) // 10}" if cuda_raw else None
+        ecc = self._q("nvmlDeviceGetEccMode", h)
+        limit = self._q("nvmlDeviceGetPowerManagementLimit", h)
+        default = self._q("nvmlDeviceGetPowerManagementDefaultLimit", h)
+        mig = self._q("nvmlDeviceGetMigMode", h)
+        cause = _const(nv, "NVML_PAGE_RETIREMENT_CAUSE_MULTIPLE_SINGLE_BIT_ECC_ERRORS", default=0)
+        retired = self._q("nvmlDeviceGetRetiredPages", h, cause)
+        # (correctable rows, uncorrectable rows, remap pending, remap failure occurred)
+        remap = self._q("nvmlDeviceGetRemappedRows", h)
+        remap_ok = isinstance(remap, (tuple, list)) and len(remap) >= 4
+        return GpuInventory(
+            model_name=_text(nv.nvmlDeviceGetName(h)),
+            uuid_hash=hash_uuid(uuid),
+            driver=_text(nv.nvmlSystemGetDriverVersion()),
+            cuda=cuda,
+            ecc_enabled=bool(ecc[0]) if ecc else None,
+            power_limit_w=limit / 1000.0 if limit is not None else None,
+            default_power_limit_w=default / 1000.0 if default is not None else None,
+            mig_enabled=bool(mig and mig[0]),
+            fractional=False,
+            retired_pages=len(retired) if retired is not None else None,
+            remapped_rows=int(remap[0]) + int(remap[1]) if remap_ok else None,
+            row_remap_pending=bool(remap[2]) if remap_ok else None,
+            row_remap_failure=bool(remap[3]) if remap_ok else None,
+        )
+
+    def _throttle_mask(self) -> int | None:
+        for name in ("nvmlDeviceGetCurrentClocksEventReasons", "nvmlDeviceGetCurrentClocksThrottleReasons"):
+            mask = self._q(name, self._h)
+            if mask is not None:
+                return int(mask)
+        return None  # unknown: recorded as a telemetry gap, never as "no throttling"
+
+    def sample(self) -> TelemetrySample:
+        nv, h = self._nv, self._h
+        temp = self._q("nvmlDeviceGetTemperature", h, _const(nv, "NVML_TEMPERATURE_GPU", default=0))
+        power = self._q("nvmlDeviceGetPowerUsage", h)
+        clock = self._q("nvmlDeviceGetClockInfo", h, _const(nv, "NVML_CLOCK_SM", default=1))
+        fan = self._q("nvmlDeviceGetFanSpeed", h)
+        mask = self._throttle_mask()
+        ecc = self._q(
+            "nvmlDeviceGetTotalEccErrors",
+            h,
+            _const(nv, "NVML_MEMORY_ERROR_TYPE_UNCORRECTED", default=1),
+            _const(nv, "NVML_VOLATILE_ECC", default=0),
+        )
+        reasons: frozenset[str] | None = None
+        if mask is not None:
+            names = {
+                "thermal": _reason_bit(nv, "HwThermalSlowdown") | _reason_bit(nv, "SwThermalSlowdown"),
+                "power": _reason_bit(nv, "SwPowerCap") | _reason_bit(nv, "HwPowerBrakeSlowdown"),
+            }
+            reasons = frozenset(name for name, bits in names.items() if mask & bits)
+        return TelemetrySample(
+            t_s=time.monotonic() - self._t0,
+            temp_c=float(temp) if temp is not None else None,
+            power_w=power / 1000.0 if power is not None else None,
+            sm_clock_mhz=float(clock) if clock is not None else None,
+            fan_pct=float(fan) if fan is not None else None,
+            throttle_reasons=reasons,
+            ecc_volatile=int(ecc) if ecc is not None else None,
+            achieved_tflops=None,  # supplied by the load generator, not NVML
+        )
+
+    def busy(self) -> bool | None:
+        procs = self._q("nvmlDeviceGetComputeRunningProcesses", self._h)
+        return None if procs is None else len(procs) > 0