workloadtruth-cli 0.1.0__py3-none-any.whl

workloadtruth/mcp_server.py

@@ -0,0 +1,89 @@
+"""MCP server: exposes WorkloadTruth as agent-callable tools.
+
+Requires the `mcp` extra (`pip install "workloadtruth-cli[mcp]"`). Started
+via `workloadtruth mcp` (stdio transport), so any MCP-compatible agent
+runtime can call classify_workload / run_benchmark / verify_audit_log
+directly instead of shelling out to the CLI and parsing text.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from mcp.server.fastmcp import FastMCP
+
+from workloadtruth.audit_log import append_entry, build_entry, last_hash, verify_chain
+from workloadtruth.classifier.rules import classify
+from workloadtruth.telemetry import get_backend
+
+DEFAULT_LOG_PATH = Path("workloadtruth.log.jsonl")
+
+
+def build_app(default_backend: str = "nvml") -> FastMCP:
+    app = FastMCP("workloadtruth")
+
+    @app.tool()
+    def classify_workload(
+        backend: str = default_backend,
+        profile: str = "training",
+        gpu_index: int = 0,
+        samples: int = 10,
+        interval_seconds: float = 1.0,
+        write_to_audit_log: bool = False,
+    ) -> dict[str, Any]:
+        """Classify the current GPU workload as TRAINING, INFERENCE, or IDLE.
+
+        `backend` is "nvml" (real hardware, requires an NVIDIA GPU + driver)
+        or "synthetic" (documented synthetic traces, no GPU required --
+        useful for testing agent integrations). `profile` only applies to
+        the synthetic backend ("training"/"inference"/"idle").
+        """
+        backend_kwargs = {"profile": profile} if backend == "synthetic" else {}
+        tb = get_backend(backend, **backend_kwargs)
+        try:
+            collected = list(tb.sample_window(gpu_index, samples, interval_seconds))
+        finally:
+            tb.close()
+
+        result = classify(collected)
+
+        if write_to_audit_log:
+            prev = last_hash(DEFAULT_LOG_PATH)
+            entry = build_entry(
+                timestamp=collected[-1].timestamp,
+                gpu_index=result.gpu_index,
+                workload_type=result.workload_type.value,
+                confidence=result.confidence,
+                reasons=result.reasons,
+                features=result.features,
+                prev_hash=prev,
+            )
+            append_entry(DEFAULT_LOG_PATH, entry)
+
+        return result.to_dict()
+
+    @app.tool()
+    def run_benchmark(trials: int = 50, window: int = 30) -> dict[str, Any]:
+        """Run the evasion-robustness benchmark against synthetic telemetry.
+
+        Returns per-profile accuracy under clean and evasion-obfuscated
+        conditions. Explicitly synthetic -- not comparable to any
+        real-hardware benchmark, see the returned "note" field.
+        """
+        from workloadtruth.benchmark import run_benchmark as _run_benchmark
+
+        return _run_benchmark(trials_per_cell=trials, window_size=window).to_dict()
+
+    @app.tool()
+    def verify_audit_log(log_file: str = str(DEFAULT_LOG_PATH)) -> dict[str, Any]:
+        """Verify the hash chain of the local audit log has not been tampered with."""
+        is_valid, message, count = verify_chain(Path(log_file))
+        return {"valid": is_valid, "message": message, "entries": count}
+
+    return app
+
+
+def run_server(default_backend: str = "nvml") -> None:
+    app = build_app(default_backend=default_backend)
+    app.run()

workloadtruth/telemetry/__init__.py

@@ -0,0 +1,22 @@
+from typing import Any
+
+from workloadtruth.telemetry.base import TelemetryBackend
+from workloadtruth.telemetry.synthetic_backend import SyntheticBackend
+
+__all__ = ["TelemetryBackend", "SyntheticBackend", "get_backend"]
+
+
+def get_backend(name: str, **kwargs: Any) -> TelemetryBackend:
+    """Resolve a telemetry backend by name.
+
+    Adding a new GPU vendor (AMD ROCm, Intel Level Zero, etc.) means
+    implementing TelemetryBackend and registering it here -- the classifier
+    and CLI never need to change.
+    """
+    if name == "synthetic":
+        return SyntheticBackend(**kwargs)
+    if name == "nvml":
+        from workloadtruth.telemetry.nvml_backend import NVMLBackend
+
+        return NVMLBackend(**kwargs)
+    raise ValueError(f"Unknown telemetry backend: {name!r}. Expected 'synthetic' or 'nvml'.")

workloadtruth/telemetry/base.py

@@ -0,0 +1,46 @@
+"""Telemetry backend interface.
+
+Every GPU vendor/data-source WorkloadTruth supports implements this one
+interface. The classifier and CLI only ever depend on TelemetryBackend, never
+on a specific vendor's SDK -- this is what lets a new backend (AMD ROCm,
+Intel Level Zero, a recorded trace file) be added without touching
+classification logic.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Iterator
+
+from workloadtruth.types import TelemetrySample
+
+
+class TelemetryBackend(ABC):
+    """Yields TelemetrySample readings for one or more GPUs."""
+
+    @abstractmethod
+    def device_count(self) -> int:
+        """Number of GPUs this backend can read from."""
+
+    @abstractmethod
+    def sample(self, gpu_index: int) -> TelemetrySample:
+        """Take one instantaneous reading from the given GPU."""
+
+    def sample_window(
+        self, gpu_index: int, count: int, interval_seconds: float
+    ) -> Iterator[TelemetrySample]:
+        """Take `count` readings, `interval_seconds` apart.
+
+        Backends that already produce a fixed trace (e.g. SyntheticBackend in
+        replay mode) may override this for determinism instead of sleeping.
+        """
+        import time
+
+        for i in range(count):
+            yield self.sample(gpu_index)
+            if i < count - 1:
+                time.sleep(interval_seconds)
+
+    def close(self) -> None:
+        """Release any backend resources. Default: no-op."""
+        return None

workloadtruth/telemetry/nvml_backend.py

@@ -0,0 +1,56 @@
+"""Real NVIDIA telemetry backend, via NVML (pynvml / nvidia-ml-py).
+
+Requires the `nvml` extra (`pip install "workloadtruth-cli[nvml]"`) and an
+NVIDIA driver on the host. Not exercised in CI or unit tests -- there is no
+NVIDIA GPU in this project's build/test environment, so this module is
+validated manually against real hardware, not covered by the test-coverage
+gate (see pyproject.toml's `[tool.coverage.run]` omit list).
+"""
+
+from __future__ import annotations
+
+import time
+
+from workloadtruth.telemetry.base import TelemetryBackend
+from workloadtruth.types import TelemetrySample
+
+try:
+    import pynvml
+except ImportError as exc:  # pragma: no cover - exercised only without the extra installed
+    raise ImportError(
+        "The NVML backend requires the 'nvml' extra: pip install \"workloadtruth-cli[nvml]\""
+    ) from exc
+
+
+class NVMLBackend(TelemetryBackend):
+    def __init__(self) -> None:
+        pynvml.nvmlInit()
+        self._device_count: int = int(pynvml.nvmlDeviceGetCount())
+
+    def device_count(self) -> int:
+        return self._device_count
+
+    def sample(self, gpu_index: int) -> TelemetrySample:
+        handle = pynvml.nvmlDeviceGetHandleByIndex(gpu_index)
+        util = pynvml.nvmlDeviceGetUtilizationRates(handle)
+        mem = pynvml.nvmlDeviceGetMemoryInfo(handle)
+        power_mw = pynvml.nvmlDeviceGetPowerUsage(handle)
+        try:
+            processes = pynvml.nvmlDeviceGetComputeRunningProcesses(handle)
+            process_count = len(processes)
+        except pynvml.NVMLError:
+            process_count = 0
+
+        return TelemetrySample(
+            timestamp=time.time(),
+            gpu_index=gpu_index,
+            gpu_utilization_pct=float(util.gpu),
+            memory_utilization_pct=float(util.memory),
+            memory_used_mib=mem.used / (1024 * 1024),
+            memory_total_mib=mem.total / (1024 * 1024),
+            power_draw_watts=power_mw / 1000.0,
+            process_count=process_count,
+        )
+
+    def close(self) -> None:
+        pynvml.nvmlShutdown()

workloadtruth/telemetry/synthetic_backend.py

@@ -0,0 +1,151 @@
+"""Synthetic telemetry backend.
+
+Generates GPU telemetry traces from documented statistical profiles instead
+of reading real hardware. This exists for two honest reasons, not as a
+substitute for real measurement:
+
+1. Unit testing the classifier without requiring NVIDIA hardware in CI.
+2. Powering `workloadtruth benchmark` on machines with no GPU (including the
+   machine this project was built on). Benchmark output produced by this
+   backend is always labeled "synthetic" -- see benchmark.py -- and must
+   never be presented as a live-hardware accuracy measurement.
+
+Profile design rationale (documented so the numbers are inspectable, not
+asserted):
+
+- TRAINING: sustained high GPU utilization (large matmul-heavy forward/
+  backward passes keep SMs busy), memory usage grows in a step pattern
+  (activations + gradient buffers + optimizer state accumulate, then drop at
+  checkpoint boundaries), power draw stays near the sustained-load ceiling
+  with low variance.
+- INFERENCE: bursty GPU utilization driven by request arrival (idle between
+  requests, a short spike to serve one), memory usage is comparatively flat
+  (model weights resident, no growing gradient/optimizer state), power draw
+  has high variance tracking the request bursts.
+- IDLE: near-zero utilization and power draw, flat low memory (driver/CUDA
+  context overhead only).
+
+These are simplified textbook characterizations, not fit to any real dataset
+-- the honest limitation to disclose is that real-world workloads (small
+inference batches with periodic re-warming, gradient-accumulation training
+with long low-utilization gaps, mixed inference+LoRA-finetuning servers) can
+blur these boundaries. The classifier's rule thresholds and this generator's
+profiles are documented in the same place (this file and rules.py) so both
+can be inspected and challenged together.
+"""
+
+from __future__ import annotations
+
+import random
+
+from workloadtruth.telemetry.base import TelemetryBackend
+from workloadtruth.types import TelemetrySample
+
+_PROFILES = {
+    "training": {
+        "gpu_util_mean": 88.0,
+        "gpu_util_std": 4.0,
+        "mem_util_mean": 70.0,
+        "mem_util_std": 6.0,
+        "mem_base_mib": 18000.0,
+        "mem_growth_mib_per_sample": 120.0,
+        "mem_ceiling_mib": 38000.0,
+        "power_mean_watts": 340.0,
+        "power_std_watts": 12.0,
+        "process_count": 1,
+    },
+    "inference": {
+        "gpu_util_mean": 35.0,
+        "gpu_util_std": 28.0,
+        "mem_util_mean": 22.0,
+        "mem_util_std": 5.0,
+        "mem_base_mib": 9000.0,
+        "mem_growth_mib_per_sample": 0.0,
+        "mem_ceiling_mib": 9500.0,
+        "power_mean_watts": 160.0,
+        "power_std_watts": 55.0,
+        "process_count": 1,
+    },
+    "idle": {
+        "gpu_util_mean": 1.0,
+        "gpu_util_std": 1.0,
+        "mem_util_mean": 0.5,
+        "mem_util_std": 0.5,
+        "mem_base_mib": 400.0,
+        "mem_growth_mib_per_sample": 0.0,
+        "mem_ceiling_mib": 400.0,
+        "power_mean_watts": 35.0,
+        "power_std_watts": 5.0,
+        "process_count": 0,
+    },
+}
+
+MEMORY_TOTAL_MIB = 40960.0  # A100 40GB, used as the fixed reference card
+
+
+def _clamp(value: float, low: float, high: float) -> float:
+    return max(low, min(high, value))
+
+
+class SyntheticBackend(TelemetryBackend):
+    """Generates telemetry from a named profile ("training"/"inference"/"idle").
+
+    `evasion` applies a documented obfuscation transform meant to defeat a
+    naive classifier: it caps utilization swings, injects artificial idle
+    gaps into a training profile, and flattens memory growth -- modeling an
+    operator deliberately trying to make a training job telemetry-resemble
+    inference. This is what `workloadtruth benchmark` uses to measure the
+    classifier's evasion-robustness gap, the same property arXiv:2606.19262
+    reports a real accuracy drop against (43-87%) -- WorkloadTruth's own
+    number, measured against this synthetic evasion transform, is reported
+    separately in the README and must never be presented as the same
+    measurement.
+    """
+
+    def __init__(self, profile: str = "training", evasion: bool = False, seed: int | None = None):
+        if profile not in _PROFILES:
+            raise ValueError(
+                f"Unknown synthetic profile: {profile!r}. Expected one of {list(_PROFILES)}."
+            )
+        self.profile_name = profile
+        self.evasion = evasion
+        self._rng = random.Random(seed)
+        self._sample_index = 0
+        self._t0 = 0.0
+
+    def device_count(self) -> int:
+        return 1
+
+    def sample(self, gpu_index: int = 0) -> TelemetrySample:
+        p = _PROFILES[self.profile_name]
+        gpu_util = self._rng.gauss(p["gpu_util_mean"], p["gpu_util_std"])
+        mem_util = self._rng.gauss(p["mem_util_mean"], p["mem_util_std"])
+        power = self._rng.gauss(p["power_mean_watts"], p["power_std_watts"])
+        mem_used = p["mem_base_mib"] + p["mem_growth_mib_per_sample"] * self._sample_index
+        mem_used = min(mem_used, p["mem_ceiling_mib"])
+        process_count = int(p["process_count"])
+
+        if self.evasion:
+            # Cap utilization swings and flatten memory growth to mimic an
+            # operator deliberately disguising a training job as inference.
+            gpu_util = _clamp(gpu_util, 0.0, 55.0)
+            mem_used = min(mem_used, p["mem_base_mib"] * 1.1)
+            if self._sample_index % 4 == 0:
+                gpu_util *= 0.2  # inject an artificial idle gap
+
+        self._sample_index += 1
+        timestamp = self._t0 + self._sample_index
+
+        return TelemetrySample(
+            timestamp=timestamp,
+            gpu_index=gpu_index,
+            gpu_utilization_pct=_clamp(gpu_util, 0.0, 100.0),
+            memory_utilization_pct=_clamp(mem_util, 0.0, 100.0),
+            memory_used_mib=_clamp(mem_used, 0.0, MEMORY_TOTAL_MIB),
+            memory_total_mib=MEMORY_TOTAL_MIB,
+            power_draw_watts=max(0.0, power),
+            process_count=process_count,
+        )
+
+    def close(self) -> None:
+        return None

workloadtruth/types.py

@@ -0,0 +1,50 @@
+"""Shared types for WorkloadTruth."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+
+class WorkloadType(str, Enum):
+    TRAINING = "TRAINING"
+    INFERENCE = "INFERENCE"
+    IDLE = "IDLE"
+    UNKNOWN = "UNKNOWN"
+
+
+@dataclass(frozen=True)
+class TelemetrySample:
+    """One point-in-time reading from a GPU telemetry backend."""
+
+    timestamp: float
+    gpu_index: int
+    gpu_utilization_pct: float
+    memory_utilization_pct: float
+    memory_used_mib: float
+    memory_total_mib: float
+    power_draw_watts: float
+    process_count: int
+
+
+@dataclass(frozen=True)
+class ClassificationResult:
+    workload_type: WorkloadType
+    confidence: float
+    gpu_index: int
+    window_seconds: float
+    sample_count: int
+    reasons: list[str] = field(default_factory=list)
+    features: dict[str, float] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "workload_type": self.workload_type.value,
+            "confidence": round(self.confidence, 4),
+            "gpu_index": self.gpu_index,
+            "window_seconds": self.window_seconds,
+            "sample_count": self.sample_count,
+            "reasons": self.reasons,
+            "features": {k: round(v, 4) for k, v in self.features.items()},
+        }

workloadtruth_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,220 @@
+Metadata-Version: 2.4
+Name: workloadtruth-cli
+Version: 0.1.0
+Summary: Classify a GPU workload as inference or training from telemetry alone, no application changes required.
+Project-URL: Homepage, https://github.com/RudrenduPaul/WorkloadTruth
+Project-URL: Repository, https://github.com/RudrenduPaul/WorkloadTruth
+Project-URL: Issues, https://github.com/RudrenduPaul/WorkloadTruth/issues
+Project-URL: Changelog, https://github.com/RudrenduPaul/WorkloadTruth/blob/main/CHANGELOG.md
+Author: Rudrendu Paul
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: agent-tools,ai-governance,compute-monitoring,cuda,finops,gpu,mcp,mlops,nvml,observability
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: System :: Hardware
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.9
+Requires-Dist: click>=8.1
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.2; extra == 'mcp'
+Provides-Extra: nvml
+Requires-Dist: nvidia-ml-py>=12.560; extra == 'nvml'
+Description-Content-Type: text/markdown
+
+# WorkloadTruth
+
+**Classify a GPU workload as `TRAINING`, `INFERENCE`, or `IDLE` from telemetry alone. No code changes to the workload, no self-reported job labels.**
+
+[![CI](https://github.com/RudrenduPaul/WorkloadTruth/actions/workflows/ci.yml/badge.svg)](https://github.com/RudrenduPaul/WorkloadTruth/actions/workflows/ci.yml)
+[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue)](pyproject.toml)
+
+Every GPU scheduler in common use today, including [run:ai](https://docs.run.ai/v2.20/Researcher/workloads/inference/inference-overview/), Slurm, and Kubernetes GPU operators, asks you to *declare* whether a job is training or inference at submission time. None of them check. WorkloadTruth reads GPU telemetry (utilization, memory pattern, power draw) and answers the question independently, so a mislabeled or misbehaving job doesn't go unnoticed.
+
+## Quick summary
+
+- **Install:** `pip install "workloadtruth-cli[nvml]"` for real GPU access, or `pip install workloadtruth-cli` to try it with the synthetic backend, no GPU needed
+- **Use it for:** catching cost-misallocated GPU jobs (a job billed as low-priority "inference" that's actually running full training) and unauthorized workload changes (an inference endpoint that starts training on live traffic without sign-off)
+- **What it's not:** a compliance or regulatory-audit tool. No regulation currently requires this kind of monitoring, see [What WorkloadTruth is not](#what-workloadtruth-is-not) below
+- **Prior art:** builds on and cites [arXiv:2606.19262](https://arxiv.org/abs/2606.19262) (ICML 2026), see [Relationship to prior research](#relationship-to-prior-research)
+
+## Install
+
+```bash
+# Real NVIDIA GPU telemetry (requires an NVIDIA driver on the host)
+pip install "workloadtruth-cli[nvml]"
+
+# Try it without a GPU, using the synthetic backend
+pip install workloadtruth-cli
+
+# npm launcher (thin wrapper around the PyPI package, see "Why two registries")
+npx workloadtruth-cli --help
+```
+
+## Quickstart
+
+```bash
+# No GPU required. Classify a synthetic "training" telemetry trace.
+$ workloadtruth classify --backend synthetic --profile training --samples 10 --interval 0
+workload_type : TRAINING
+confidence    : 1.00
+gpu_index     : 0
+samples       : 10 over 9.0s
+reasons:
+  - avg GPU utilization 87.8% >= training threshold 65.0%
+  - low GPU utilization variance (std=3.4) <= training ceiling 15.0
+  - memory growing 120.0 MiB/sample >= training threshold 5.0
+  - low power-draw variance (std=9.4W) <= training ceiling 25.0W
+
+# Real hardware
+$ workloadtruth classify --backend nvml --samples 10 --interval 1 --json
+```
+
+`--json` on every command switches to machine-readable output for scripts and agents.
+
+## How classification works
+
+WorkloadTruth ships a **rule-based classifier only** in v0.1: a set of documented, inspectable thresholds over four features extracted from a telemetry window (average and variance of GPU utilization, memory-growth slope, average and variance of power draw). Every threshold lives as a named constant in [`src/workloadtruth/classifier/rules.py`](src/workloadtruth/classifier/rules.py) with a comment explaining its intuition. Nothing is a black box.
+
+`--experimental` (an ML-based classifier) is present as a flag but fails loudly with an explanation rather than shipping a fake result. [arXiv:2606.19262](https://arxiv.org/abs/2606.19262)'s trained model and dataset were never published, and this project has no NVIDIA GPU in its build environment to collect real training data. An ML classifier ships here only once it's trained on a real, disclosed dataset and independently shown to beat the rule-based baseline, not before.
+
+## Benchmark
+
+`workloadtruth benchmark` measures the classifier's accuracy against documented synthetic GPU telemetry traces (see [`synthetic_backend.py`](src/workloadtruth/telemetry/synthetic_backend.py) for the exact profile parameters), both clean and under a deliberate evasion transform that mimics an operator disguising a training job as inference (capping utilization swings, flattening memory growth, injecting artificial idle gaps).
+
+**This is run on synthetic data, not live NVIDIA hardware, so it is not directly comparable to arXiv:2606.19262's real-hardware numbers.** Both are reported below, side by side, never blended into one figure.
+
+| | arXiv:2606.19262 (real hardware, NVML) | WorkloadTruth v0.1 (synthetic traces, 300 trials/cell) |
+|---|---|---|
+| Clean accuracy | 98.2% | 100.0% |
+| Evasion accuracy | 43-87% | 66.7% overall |
+
+The overall evasion number hides the real finding. Broken out by workload type, WorkloadTruth's rule-based classifier is currently **completely fooled on evasive training workloads (0% accuracy)**, while staying accurate on evasive inference and idle traces (100% each). Capping GPU utilization alone is enough to make a training job read as inference to this classifier today.
+
+| Profile | Clean accuracy | Evasion accuracy |
+|---|---|---|
+| Training | 100.0% | **0.0%** |
+| Inference | 100.0% | 100.0% |
+| Idle | 100.0% | 100.0% |
+
+This is the concrete, disclosed gap the benchmark suite exists to surface and track, not a footnote. A rule-based classifier that only looks at utilization variance is trivially evadable. Closing this gap, through multi-signal fusion or a real trained classifier once data exists, is the roadmap, not a solved problem. Reproduce it yourself:
+
+```bash
+workloadtruth benchmark --trials 300 --window 30 --json
+```
+
+## CLI reference
+
+```
+$ workloadtruth --help
+Usage: workloadtruth [OPTIONS] COMMAND [ARGS]...
+
+  Classify a GPU workload as INFERENCE, TRAINING, or IDLE from telemetry
+  alone.
+
+Options:
+  --version  Show the version and exit.
+  --help     Show this message and exit.
+
+Commands:
+  benchmark   Run the evasion-robustness benchmark against synthetic...
+  classify    One-shot classification of the current GPU workload.
+  mcp         Start an MCP server exposing classify/benchmark/verify-log...
+  verify-log  Verify the hash chain of a local audit log has not been...
+  watch       Continuously classify and append hash-chained entries to...
+```
+
+| Command | Purpose |
+|---|---|
+| `classify` | One-shot classification. `--backend synthetic\|nvml`, `--json` for machine-readable output. |
+| `watch` | Continuous classification; appends a hash-chained entry to a local audit log on every window. |
+| `benchmark` | Runs the evasion-robustness benchmark (see above). |
+| `verify-log` | Re-derives every audit-log entry's hash and confirms the chain hasn't been tampered with. |
+| `mcp` | Starts an MCP server (stdio) exposing `classify_workload`, `run_benchmark`, `verify_audit_log` as agent-callable tools. Requires `pip install "workloadtruth-cli[mcp]"`. |
+
+Every command supports `--json`. Full flag reference: `workloadtruth <command> --help`.
+
+## Agent-native (MCP + A2A)
+
+```bash
+pip install "workloadtruth-cli[mcp]"
+workloadtruth mcp
+```
+
+Exposes three tools over stdio MCP: `classify_workload`, `run_benchmark`, `verify_audit_log`. A `.well-known/agent.json` manifest is shipped at the repo root for A2A-style discovery, listing both the CLI and MCP interfaces and the packages that provide them.
+
+## Audit log
+
+`workloadtruth watch` appends a hash-chained entry to `workloadtruth.log.jsonl` on every classification window. Each entry's hash covers its own content plus the previous entry's hash, so any edit, reorder, or deletion after the fact breaks the chain from that point forward. `workloadtruth verify-log` re-derives every hash and reports the first broken link, if any.
+
+This proves what was classified, when, and that the local record hasn't been silently altered afterward. **It does not prove the classification itself was correct**, and it is not evidence of regulatory compliance. See below.
+
+## Why two registries
+
+WorkloadTruth's implementation is Python. NVML access (`pynvml`/`nvidia-ml-py`) is the mature, official way to read NVIDIA GPU telemetry, and it's also what the closest prior art ([arXiv:2606.19262](https://arxiv.org/abs/2606.19262)) uses. The npm package (`workloadtruth-cli`) is a thin launcher, not a reimplementation. It locates and execs the real `workloadtruth` binary installed from PyPI, so `npx workloadtruth-cli` works for npm-first agent tooling without duplicating the classifier in two languages.
+
+## Comparison
+
+| | WorkloadTruth | NVIDIA DCGM / `dcgm-exporter` | run:ai | Weights & Biases |
+|---|---|---|---|---|
+| Reads GPU telemetry | Yes (via NVML) | Yes (source) | Yes | Yes |
+| Classifies workload type automatically | **Yes** | No, exposes raw metrics only | No, workload type is user-declared at job submission | No, training-run-scoped by design, no classification |
+| Local, hash-chained audit trail | Yes | No | No | No |
+| Evasion-robustness benchmark | Yes (documented, reproducible) | N/A | N/A | N/A |
+| Requires an NVIDIA GPU | Only for the `nvml` backend; the `synthetic` backend works without one | Yes | Yes | No (general system metrics) |
+
+Checked directly against each project's own documentation: [DCGM exporter docs](https://docs.nvidia.com/datacenter/dcgm/latest/gpu-telemetry/dcgm-exporter.html), [run:ai inference overview](https://docs.run.ai/v2.20/Researcher/workloads/inference/inference-overview/), [W&B system metrics docs](https://docs.wandb.ai/models/ref/python/experiments/system-metrics). None of these classify workload type from telemetry alone. That gap is what WorkloadTruth fills.
+
+## Relationship to prior research
+
+WorkloadTruth's core technique, classifying training vs. non-training GPU activity from telemetry, is not novel. It's the direct application of a real, active research thread:
+
+1. Yonadav Shavit (Harvard), [*"What does it take to catch a Chinchilla?"*](https://arxiv.org/abs/2303.11341) (2023): proposed hardware-level "training transcripts" for verifying large training runs.
+2. GovAI, [*"Computing Power and the Governance of AI"*](https://www.governance.ai/analysis/computing-power-and-the-governance-of-ai) (2024): surveyed compute-governance mechanisms, explicitly framed as exploratory, not endorsed policy.
+3. [*"Hardware-Enabled Mechanisms for Verifying Responsible AI Development"*](https://arxiv.org/abs/2505.03742) (2025): hardware-security researchers proposing on-chip attestation.
+4. Rahman & Tajdari, [*"Detecting Hidden ML Training With Zero-Overhead Telemetry"*](https://arxiv.org/abs/2606.19262) (ICML 2026 Technical AI Governance workshop): a working NVML-telemetry classifier, 98.2% accurate on unobfuscated workloads, the direct prior art for this project's core classification technique.
+
+**What WorkloadTruth adds:** as of this project's own research (2026-07-19), no open-source, installable implementation of this research thread existed, only academic prototypes. WorkloadTruth is that packaging: a real CLI, an MCP server, a hash-chained audit log, and a reproducible evasion-robustness benchmark, built in the open. It does not claim to improve on the paper's classification technique. See the benchmark section above: the current rule-based classifier is considerably more evadable than the paper's ML approach on the one axis it measures.
+
+## What WorkloadTruth is not
+
+- **Not a compliance or regulatory-audit tool.** No law currently requires inference/training classification or reporting. Any future claim otherwise will name the specific enacted regulation; none exists as of this writing.
+- **Not a content inspector.** WorkloadTruth reads GPU-level signals only (utilization, memory, power). It never inspects model weights, training data, prompts, or completions.
+- **Not proof of "compliant" or "safe" operation.** The audit log proves what was classified and when, and that the record wasn't altered afterward, not that the classification was correct or that any policy was followed.
+
+## FAQ
+
+**Does this need an NVIDIA GPU?**
+Only for the `nvml` backend. `--backend synthetic` runs the full classifier and CLI against documented synthetic traces, no GPU required. Useful for trying the tool or for CI.
+
+**Can it classify AMD or Intel GPU workloads?**
+Not in v0.1. The telemetry layer is a pluggable interface (`TelemetryBackend`) specifically so a new vendor backend (AMD ROCm, Intel Level Zero) can be added without touching the classifier. See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+**Is the classifier accurate enough to bill or penalize someone based on its output?**
+Not yet, and the benchmark section above is the honest reason why: 0% accuracy on evasive training workloads today. Treat `workload_type` as a signal to investigate, not a verdict.
+
+**Why not just use the ML classifier from the paper?**
+Its trained weights and dataset were never published. Reimplementing an ML classifier without real training data would produce an unvalidated accuracy claim, not a measured one. See [How classification works](#how-classification-works).
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). Security issues: see [SECURITY.md](SECURITY.md).
+
+## License
+
+[Apache 2.0](LICENSE)

workloadtruth_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+workloadtruth/__init__.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+workloadtruth/audit_log.py,sha256=AEzgA1pu42rLe3ERdNXBxgTK2K5cnHax9M1Rxtfim8E,4786
+workloadtruth/benchmark.py,sha256=xdIUuDaLVLFw6ED1_qsKH-7CeDrVMLbrxR2jtJuUDFE,4113
+workloadtruth/cli.py,sha256=tZLTJmv3E-KOuczbDmhSVN9F8UQ3ExyCQUkOuiXNeKY,7113
+workloadtruth/mcp_server.py,sha256=OztucxHqKMVt1tCX63CCJA99z169BCQGifrtdZGtL2Y,3302
+workloadtruth/types.py,sha256=Ow_sBBaR4F_0pfomCgjDe8WkWMzRFIPolgKk_XZEKa4,1335
+workloadtruth/classifier/__init__.py,sha256=HoVpv_hgZ9tSR1Vx3T4g8xV2qdEvjYJQxTMgvgCNwXU,114
+workloadtruth/classifier/experimental.py,sha256=k8nAjxRb_-4XQXA7gju9mUary_A80M_2VTJS61774rU,1210
+workloadtruth/classifier/rules.py,sha256=P-PJjspMGjA5HyekyazA542UhPhLLa9DSWzhG_lKyMw,7308
+workloadtruth/telemetry/__init__.py,sha256=qdOZGPY8Z00dnouojwcOobgVY4deVfaEmkYMJypno5M,811
+workloadtruth/telemetry/base.py,sha256=1mtmhISGLQNyaeNgwoaiebnYDTY7KHELJ4O0NPXCxpg,1491
+workloadtruth/telemetry/nvml_backend.py,sha256=FDChP60SWxOwhYozNZ6cmE2cMcbAUkLTRqmOuqR2oGE,2029
+workloadtruth/telemetry/synthetic_backend.py,sha256=0w1pdcA6DKMGIHyZmdMmUT8mk-qiaxyc1dWP5EXn9uA,6049
+workloadtruth_cli-0.1.0.dist-info/METADATA,sha256=cuOFBHfMlHtlOVCRn61qdlej-4gTGOc3M4Hs9iVeWDg,14766
+workloadtruth_cli-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+workloadtruth_cli-0.1.0.dist-info/entry_points.txt,sha256=WiGvdk4T12N13puDy9-1l6TShdQpNpkQ-2KFzXNjLnc,57
+workloadtruth_cli-0.1.0.dist-info/licenses/LICENSE,sha256=vWCQIFSDq8K7yxYvTAwPAT7d5PG2Czswa2NQnJbNw74,10758
+workloadtruth_cli-0.1.0.dist-info/RECORD,,

workloadtruth_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

workloadtruth_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+workloadtruth = workloadtruth.cli:main