workloadtruth-cli 0.1.0__tar.gz → 0.1.1__tar.gz

{workloadtruth_cli-0.1.0 → workloadtruth_cli-0.1.1}/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.1.1 -- 2026-07-19
+
+Docs-only release. README gets a real demo GIF, a table of contents, a
+dedicated "What is WorkloadTruth" section, and 3 more FAQ entries
+(comparison, platform compatibility, licensing). No code changes.
+
 ## 0.1.0 -- 2026-07-19
 
 Initial release.

{workloadtruth_cli-0.1.0 → workloadtruth_cli-0.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: workloadtruth-cli
-Version: 0.1.0
+Version: 0.1.1
 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
@@ -41,11 +41,31 @@ Description-Content-Type: text/markdown
 **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)
+[![PyPI](https://img.shields.io/pypi/v/workloadtruth-cli)](https://pypi.org/project/workloadtruth-cli/)
 [![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)
 
+![WorkloadTruth classifying a synthetic training workload, then running the evasion-robustness benchmark](https://raw.githubusercontent.com/RudrenduPaul/WorkloadTruth/main/docs/demo.gif)
+
 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.
 
+## Table of contents
+
+- [Quick summary](#quick-summary)
+- [Install](#install)
+- [Quickstart](#quickstart)
+- [How classification works](#how-classification-works)
+- [Benchmark](#benchmark)
+- [CLI reference](#cli-reference)
+- [Agent-native (MCP + A2A)](#agent-native-mcp--a2a)
+- [Audit log](#audit-log)
+- [Why two registries](#why-two-registries)
+- [Comparison](#comparison)
+- [What is WorkloadTruth, and why does it exist](#what-is-workloadtruth-and-why-does-it-exist)
+- [Relationship to prior research](#relationship-to-prior-research)
+- [What WorkloadTruth is not](#what-workloadtruth-is-not)
+- [FAQ](#faq)
+
 ## 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
@@ -180,6 +200,12 @@ WorkloadTruth's implementation is Python. NVML access (`pynvml`/`nvidia-ml-py`)
 
 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.
 
+## What is WorkloadTruth, and why does it exist
+
+WorkloadTruth is an open-source command-line tool and MCP server that classifies a running GPU workload as `TRAINING`, `INFERENCE`, or `IDLE` using only GPU-level telemetry (utilization, memory pattern, power draw), with no changes to the workload's own code and no reliance on a self-reported job label.
+
+It exists because every mainstream GPU scheduler asks the job's owner to declare its type at submission time and never checks that declaration against what the hardware is actually doing. That gap has two real consequences: cost misallocation (a job scheduled at low-priority "inference" pricing that is actually running full training) and unauthorized workload changes (an inference endpoint that quietly starts training on live traffic). WorkloadTruth closes that verification gap today, and doubles as the first open, installable implementation of a real academic research thread on verifying AI training runs from hardware telemetry (see below).
+
 ## 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:
@@ -211,6 +237,15 @@ Not yet, and the benchmark section above is the honest reason why: 0% accuracy o
 **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).
 
+**How is this different from run:ai or NVIDIA DCGM?**
+run:ai and DCGM both expose or use GPU telemetry, but neither classifies workload type from that telemetry. run:ai relies entirely on the label the job's owner declares at submission; DCGM just exposes raw utilization and memory metrics for something else to interpret. WorkloadTruth is the layer that actually looks at the telemetry and answers the question. See the [comparison table](#comparison).
+
+**Does this work on Windows, macOS, and Linux?**
+The `synthetic` backend runs anywhere Python 3.9+ runs, including this project's own macOS build environment (which has no NVIDIA GPU). The `nvml` backend requires an NVIDIA GPU and driver, which in practice means Linux or Windows with NVIDIA hardware; NVML itself is not available on macOS.
+
+**What license is this under, and can I use it commercially?**
+Apache 2.0. Commercial use, modification, and redistribution are all permitted under its terms; see [LICENSE](LICENSE).
+
 ## Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md). Security issues: see [SECURITY.md](SECURITY.md).

{workloadtruth_cli-0.1.0 → workloadtruth_cli-0.1.1}/README.md

@@ -3,11 +3,31 @@
 **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)
+[![PyPI](https://img.shields.io/pypi/v/workloadtruth-cli)](https://pypi.org/project/workloadtruth-cli/)
 [![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)
 
+![WorkloadTruth classifying a synthetic training workload, then running the evasion-robustness benchmark](https://raw.githubusercontent.com/RudrenduPaul/WorkloadTruth/main/docs/demo.gif)
+
 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.
 
+## Table of contents
+
+- [Quick summary](#quick-summary)
+- [Install](#install)
+- [Quickstart](#quickstart)
+- [How classification works](#how-classification-works)
+- [Benchmark](#benchmark)
+- [CLI reference](#cli-reference)
+- [Agent-native (MCP + A2A)](#agent-native-mcp--a2a)
+- [Audit log](#audit-log)
+- [Why two registries](#why-two-registries)
+- [Comparison](#comparison)
+- [What is WorkloadTruth, and why does it exist](#what-is-workloadtruth-and-why-does-it-exist)
+- [Relationship to prior research](#relationship-to-prior-research)
+- [What WorkloadTruth is not](#what-workloadtruth-is-not)
+- [FAQ](#faq)
+
 ## 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
@@ -142,6 +162,12 @@ WorkloadTruth's implementation is Python. NVML access (`pynvml`/`nvidia-ml-py`)
 
 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.
 
+## What is WorkloadTruth, and why does it exist
+
+WorkloadTruth is an open-source command-line tool and MCP server that classifies a running GPU workload as `TRAINING`, `INFERENCE`, or `IDLE` using only GPU-level telemetry (utilization, memory pattern, power draw), with no changes to the workload's own code and no reliance on a self-reported job label.
+
+It exists because every mainstream GPU scheduler asks the job's owner to declare its type at submission time and never checks that declaration against what the hardware is actually doing. That gap has two real consequences: cost misallocation (a job scheduled at low-priority "inference" pricing that is actually running full training) and unauthorized workload changes (an inference endpoint that quietly starts training on live traffic). WorkloadTruth closes that verification gap today, and doubles as the first open, installable implementation of a real academic research thread on verifying AI training runs from hardware telemetry (see below).
+
 ## 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:
@@ -173,6 +199,15 @@ Not yet, and the benchmark section above is the honest reason why: 0% accuracy o
 **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).
 
+**How is this different from run:ai or NVIDIA DCGM?**
+run:ai and DCGM both expose or use GPU telemetry, but neither classifies workload type from that telemetry. run:ai relies entirely on the label the job's owner declares at submission; DCGM just exposes raw utilization and memory metrics for something else to interpret. WorkloadTruth is the layer that actually looks at the telemetry and answers the question. See the [comparison table](#comparison).
+
+**Does this work on Windows, macOS, and Linux?**
+The `synthetic` backend runs anywhere Python 3.9+ runs, including this project's own macOS build environment (which has no NVIDIA GPU). The `nvml` backend requires an NVIDIA GPU and driver, which in practice means Linux or Windows with NVIDIA hardware; NVML itself is not available on macOS.
+
+**What license is this under, and can I use it commercially?**
+Apache 2.0. Commercial use, modification, and redistribution are all permitted under its terms; see [LICENSE](LICENSE).
+
 ## Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md). Security issues: see [SECURITY.md](SECURITY.md).

workloadtruth_cli-0.1.1/docs/demo.tape

@@ -0,0 +1,18 @@
+Output docs/demo.gif
+
+Set Shell "bash"
+Set FontSize 16
+Set Width 1000
+Set Height 560
+Set Padding 20
+Set Theme "Dracula"
+
+Type "workloadtruth classify --backend synthetic --profile training --samples 10 --interval 0"
+Sleep 500ms
+Enter
+Sleep 3s
+
+Type "workloadtruth benchmark --trials 30 --window 20"
+Sleep 500ms
+Enter
+Sleep 4s

{workloadtruth_cli-0.1.0 → workloadtruth_cli-0.1.1}/npm-shim/package.json

@@ -1,6 +1,6 @@
 {
   "name": "workloadtruth-cli",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Classify a GPU workload as inference or training from telemetry alone, no application changes required.",
   "keywords": [
     "gpu",

{workloadtruth_cli-0.1.0 → workloadtruth_cli-0.1.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "workloadtruth-cli"
-version = "0.1.0"
+version = "0.1.1"
 description = "Classify a GPU workload as inference or training from telemetry alone, no application changes required."
 readme = "README.md"
 license = "Apache-2.0"

workloadtruth_cli-0.1.1/src/workloadtruth/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.1"

workloadtruth_cli-0.1.0/src/workloadtruth/__init__.py

@@ -1 +0,0 @@
-__version__ = "0.1.0"