workloadtruth-cli 0.1.0__py3-none-any.whl

workloadtruth/__init__.py

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

workloadtruth/audit_log.py

@@ -0,0 +1,148 @@
+"""Hash-chained local audit log.
+
+Every `workloadtruth watch` classification event is appended to a local
+JSONL file as a hash-chained entry: each entry's hash covers its own content
+plus the previous entry's hash, so any edit, reorder, or deletion of a past
+entry breaks the chain from that point forward and is detected by
+`verify_chain`. This mirrors the audit-log pattern already shipped in this
+portfolio's `auditreach`/`tokentrust` CLIs.
+
+This proves what was classified and when, and that the local record hasn't
+been silently altered after the fact. It does NOT prove the classification
+itself was correct, and it does NOT constitute regulatory compliance
+evidence -- no regulation currently requires this. See the README's "What
+WorkloadTruth is not" section.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import asdict, dataclass
+from pathlib import Path
+from typing import Any
+
+GENESIS_HASH = "0" * 64
+
+
+def _canonical_json(obj: dict[str, Any]) -> str:
+    return json.dumps(obj, sort_keys=True, separators=(",", ":"))
+
+
+@dataclass(frozen=True)
+class AuditLogEntry:
+    timestamp: float
+    gpu_index: int
+    workload_type: str
+    confidence: float
+    reasons: list[str]
+    features: dict[str, float]
+    prev_hash: str
+    entry_hash: str
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+def _compute_entry_hash(payload: dict[str, Any], prev_hash: str) -> str:
+    body = _canonical_json(payload) + prev_hash
+    return hashlib.sha256(body.encode("utf-8")).hexdigest()
+
+
+def build_entry(
+    *,
+    timestamp: float,
+    gpu_index: int,
+    workload_type: str,
+    confidence: float,
+    reasons: list[str],
+    features: dict[str, float],
+    prev_hash: str,
+) -> AuditLogEntry:
+    rounded_confidence = round(confidence, 4)
+    rounded_features = {k: round(v, 4) for k, v in features.items()}
+    payload: dict[str, Any] = {
+        "timestamp": timestamp,
+        "gpu_index": gpu_index,
+        "workload_type": workload_type,
+        "confidence": rounded_confidence,
+        "reasons": reasons,
+        "features": rounded_features,
+    }
+    entry_hash = _compute_entry_hash(payload, prev_hash)
+    return AuditLogEntry(
+        timestamp=timestamp,
+        gpu_index=gpu_index,
+        workload_type=workload_type,
+        confidence=rounded_confidence,
+        reasons=reasons,
+        features=rounded_features,
+        prev_hash=prev_hash,
+        entry_hash=entry_hash,
+    )
+
+
+def last_hash(log_path: Path) -> str:
+    if not log_path.exists():
+        return GENESIS_HASH
+    last_line = None
+    with log_path.open("r", encoding="utf-8") as f:
+        for line in f:
+            line = line.strip()
+            if line:
+                last_line = line
+    if last_line is None:
+        return GENESIS_HASH
+    return str(json.loads(last_line)["entry_hash"])
+
+
+def append_entry(log_path: Path, entry: AuditLogEntry) -> None:
+    log_path.parent.mkdir(parents=True, exist_ok=True)
+    with log_path.open("a", encoding="utf-8") as f:
+        f.write(_canonical_json(entry.to_dict()) + "\n")
+
+
+def verify_chain(log_path: Path) -> tuple[bool, str, int]:
+    """Re-derive every entry's hash and check chain linkage.
+
+    Returns (is_valid, message, entries_checked).
+    """
+    if not log_path.exists():
+        return True, "log file does not exist yet -- nothing to verify", 0
+
+    prev_hash = GENESIS_HASH
+    count = 0
+    with log_path.open("r", encoding="utf-8") as f:
+        for line_number, raw_line in enumerate(f, start=1):
+            raw_line = raw_line.strip()
+            if not raw_line:
+                continue
+            try:
+                record = json.loads(raw_line)
+            except json.JSONDecodeError as exc:
+                return False, f"line {line_number}: invalid JSON ({exc})", count
+
+            claimed_hash = record.get("entry_hash")
+            claimed_prev = record.get("prev_hash")
+            if claimed_prev != prev_hash:
+                return (
+                    False,
+                    f"line {line_number}: prev_hash mismatch "
+                    f"(expected {prev_hash}, found {claimed_prev})",
+                    count,
+                )
+
+            payload = {k: v for k, v in record.items() if k not in ("prev_hash", "entry_hash")}
+            recomputed = _compute_entry_hash(payload, prev_hash)
+            if recomputed != claimed_hash:
+                return (
+                    False,
+                    f"line {line_number}: entry_hash mismatch -- content was modified "
+                    f"after being written (expected {recomputed}, found {claimed_hash})",
+                    count,
+                )
+
+            prev_hash = claimed_hash
+            count += 1
+
+    return True, f"chain verified, {count} entries", count

workloadtruth/benchmark.py

@@ -0,0 +1,111 @@
+"""Evasion-robustness benchmark suite.
+
+Measures the rule-based classifier's accuracy against SyntheticBackend
+traces, both "clean" and under the documented evasion transform (see
+telemetry/synthetic_backend.py). This is WorkloadTruth's core
+differentiation artifact: arXiv:2606.19262 measured a real accuracy drop
+under obfuscation (98.2% clean, 43-87% evasive) on real GPU hardware and a
+dataset that was never published. This benchmark runs the same *kind* of
+test, on synthetic data, on whatever machine `workloadtruth benchmark` is
+invoked on.
+
+The numbers this benchmark produces are NOT comparable to the paper's --
+different data, different (and much simpler) hardware simulation, no shared
+ground truth. Report them side by side in the README, labeled separately,
+never blended into one number. This is a binding rule from this project's
+own anti-sycophancy audit, not a style preference.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from workloadtruth.classifier.rules import classify
+from workloadtruth.telemetry.synthetic_backend import SyntheticBackend
+from workloadtruth.types import WorkloadType
+
+_PROFILE_TO_EXPECTED = {
+    "training": WorkloadType.TRAINING,
+    "inference": WorkloadType.INFERENCE,
+    "idle": WorkloadType.IDLE,
+}
+
+
+@dataclass(frozen=True)
+class BenchmarkCell:
+    profile: str
+    evasion: bool
+    trials: int
+    correct: int
+
+    @property
+    def accuracy(self) -> float:
+        return self.correct / self.trials if self.trials else 0.0
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "profile": self.profile,
+            "evasion": self.evasion,
+            "trials": self.trials,
+            "correct": self.correct,
+            "accuracy": round(self.accuracy, 4),
+        }
+
+
+@dataclass(frozen=True)
+class BenchmarkReport:
+    cells: list[BenchmarkCell]
+    window_size: int
+    trials_per_cell: int
+
+    @property
+    def clean_accuracy(self) -> float:
+        clean_cells = [c for c in self.cells if not c.evasion]
+        total = sum(c.trials for c in clean_cells)
+        correct = sum(c.correct for c in clean_cells)
+        return correct / total if total else 0.0
+
+    @property
+    def evasion_accuracy(self) -> float:
+        evasive_cells = [c for c in self.cells if c.evasion]
+        total = sum(c.trials for c in evasive_cells)
+        correct = sum(c.correct for c in evasive_cells)
+        return correct / total if total else 0.0
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "source": "synthetic",
+            "note": (
+                "Measured against documented synthetic GPU telemetry traces, "
+                "not live NVIDIA hardware. Not comparable to arXiv:2606.19262's "
+                "real-hardware numbers -- see benchmark.py module docstring."
+            ),
+            "window_size": self.window_size,
+            "trials_per_cell": self.trials_per_cell,
+            "clean_accuracy": round(self.clean_accuracy, 4),
+            "evasion_accuracy": round(self.evasion_accuracy, 4),
+            "cells": [c.to_dict() for c in self.cells],
+        }
+
+
+def run_benchmark(
+    trials_per_cell: int = 50, window_size: int = 30, base_seed: int = 1000
+) -> BenchmarkReport:
+    cells: list[BenchmarkCell] = []
+    for profile, expected in _PROFILE_TO_EXPECTED.items():
+        for evasion in (False, True):
+            correct = 0
+            for trial in range(trials_per_cell):
+                seed = base_seed + hash((profile, evasion, trial)) % 100_000
+                backend = SyntheticBackend(profile=profile, evasion=evasion, seed=seed)
+                samples = [backend.sample(gpu_index=0) for _ in range(window_size)]
+                result = classify(samples)
+                if result.workload_type == expected:
+                    correct += 1
+            cells.append(
+                BenchmarkCell(
+                    profile=profile, evasion=evasion, trials=trials_per_cell, correct=correct
+                )
+            )
+    return BenchmarkReport(cells=cells, window_size=window_size, trials_per_cell=trials_per_cell)

workloadtruth/classifier/__init__.py

@@ -0,0 +1,3 @@
+from workloadtruth.classifier.rules import classify, extract_features
+
+__all__ = ["classify", "extract_features"]

workloadtruth/classifier/experimental.py

@@ -0,0 +1,29 @@
+"""Placeholder for a future ML-based classifier.
+
+Per this project's own anti-sycophancy rules: an ML classifier is only
+shipped once it is independently shown to beat the rule-based baseline on a
+real, honestly-reported test set (see the execution plan's Assumption 3).
+No such model exists yet -- arXiv:2606.19262's trained weights and dataset
+were not released, and this project's build environment has no GPU to
+collect real training data on. Shipping a stub that returns fabricated
+predictions would misrepresent accuracy that was never measured, so
+`--experimental` fails loudly instead.
+"""
+
+from __future__ import annotations
+
+from typing import Any, NoReturn
+
+
+class ExperimentalClassifierUnavailable(RuntimeError):
+    pass
+
+
+def classify_experimental(*_args: Any, **_kwargs: Any) -> NoReturn:
+    raise ExperimentalClassifierUnavailable(
+        "The experimental ML classifier is not available in this release. "
+        "workloadtruth ships only the rule-based classifier (see "
+        "classifier/rules.py) until an ML classifier is trained and "
+        "independently benchmarked against it on a real, disclosed test "
+        "set. Run `workloadtruth classify` without --experimental."
+    )

workloadtruth/classifier/rules.py

@@ -0,0 +1,183 @@
+"""Rule-based workload classifier.
+
+This is the default (and, in v0.1, the only shipped) classifier. It is a
+transparent, documented heuristic, not a trained model -- every threshold
+below is a constant you can read, challenge, and override, not a black box.
+See the README's "How classification works" section for why v0.1 ships
+this instead of the ML classifier arXiv:2606.19262 describes:
+without the paper's training dataset (not published) or real GPU hardware
+in this project's build environment, an from-scratch ML classifier would be
+an unvalidated claim, not a measured one. This module is intentionally the
+inspectable alternative.
+
+Feature intuition (same rationale as synthetic_backend.py's profile design,
+kept in sync deliberately):
+
+- Training: sustained high, low-variance GPU utilization; memory usage
+  trending upward across the sampling window (activations, gradient
+  buffers, optimizer state accumulating); low-variance, near-ceiling power
+  draw.
+- Inference: bursty, high-variance GPU utilization tracking request
+  arrival; flat memory usage (resident weights, no growing training state);
+  high-variance power draw.
+- Idle: near-zero utilization and power draw across the whole window.
+"""
+
+from __future__ import annotations
+
+from workloadtruth.types import ClassificationResult, TelemetrySample, WorkloadType
+
+# Idle detection
+IDLE_GPU_UTIL_PCT = 5.0
+IDLE_POWER_WATTS = 50.0
+
+# Training signal thresholds
+TRAINING_MIN_AVG_GPU_UTIL_PCT = 65.0
+TRAINING_MAX_GPU_UTIL_STD_PCT = 15.0
+TRAINING_MIN_MEM_GROWTH_MIB_PER_SAMPLE = 5.0
+TRAINING_MAX_POWER_STD_WATTS = 25.0
+
+# Inference signal thresholds
+INFERENCE_MAX_AVG_GPU_UTIL_PCT = 70.0
+INFERENCE_MIN_GPU_UTIL_STD_PCT = 12.0
+INFERENCE_MIN_POWER_STD_WATTS = 20.0
+
+
+def _mean(values: list[float]) -> float:
+    return sum(values) / len(values) if values else 0.0
+
+
+def _stdev(values: list[float]) -> float:
+    if len(values) < 2:
+        return 0.0
+    m = _mean(values)
+    variance = sum((v - m) ** 2 for v in values) / (len(values) - 1)
+    return float(variance**0.5)
+
+
+def _linear_slope_per_sample(values: list[float]) -> float:
+    """Least-squares slope of `values` against sample index (0, 1, 2, ...)."""
+    n = len(values)
+    if n < 2:
+        return 0.0
+    xs = [float(i) for i in range(n)]
+    x_mean = _mean(xs)
+    y_mean = _mean(values)
+    numerator = sum((xs[i] - x_mean) * (values[i] - y_mean) for i in range(n))
+    denominator = sum((xs[i] - x_mean) ** 2 for i in range(n))
+    return numerator / denominator if denominator else 0.0
+
+
+def extract_features(samples: list[TelemetrySample]) -> dict[str, float]:
+    gpu_util = [s.gpu_utilization_pct for s in samples]
+    mem_used = [s.memory_used_mib for s in samples]
+    power = [s.power_draw_watts for s in samples]
+
+    return {
+        "avg_gpu_util_pct": _mean(gpu_util),
+        "std_gpu_util_pct": _stdev(gpu_util),
+        "mem_growth_mib_per_sample": _linear_slope_per_sample(mem_used),
+        "avg_power_watts": _mean(power),
+        "std_power_watts": _stdev(power),
+        "avg_process_count": _mean([float(s.process_count) for s in samples]),
+    }
+
+
+def classify(samples: list[TelemetrySample]) -> ClassificationResult:
+    if not samples:
+        raise ValueError("classify() requires at least one telemetry sample")
+
+    gpu_index = samples[0].gpu_index
+    window_seconds = samples[-1].timestamp - samples[0].timestamp if len(samples) > 1 else 0.0
+    features = extract_features(samples)
+
+    if (
+        features["avg_gpu_util_pct"] <= IDLE_GPU_UTIL_PCT
+        and features["avg_power_watts"] <= IDLE_POWER_WATTS
+    ):
+        return ClassificationResult(
+            workload_type=WorkloadType.IDLE,
+            confidence=1.0 - (features["avg_gpu_util_pct"] / IDLE_GPU_UTIL_PCT) * 0.3,
+            gpu_index=gpu_index,
+            window_seconds=window_seconds,
+            sample_count=len(samples),
+            reasons=[
+                f"avg GPU utilization {features['avg_gpu_util_pct']:.1f}% "
+                f"<= idle threshold {IDLE_GPU_UTIL_PCT}%",
+                f"avg power draw {features['avg_power_watts']:.1f}W "
+                f"<= idle threshold {IDLE_POWER_WATTS}W",
+            ],
+            features=features,
+        )
+
+    training_votes: list[str] = []
+    inference_votes: list[str] = []
+
+    if features["avg_gpu_util_pct"] >= TRAINING_MIN_AVG_GPU_UTIL_PCT:
+        training_votes.append(
+            f"avg GPU utilization {features['avg_gpu_util_pct']:.1f}% "
+            f">= training threshold {TRAINING_MIN_AVG_GPU_UTIL_PCT}%"
+        )
+    if features["std_gpu_util_pct"] <= TRAINING_MAX_GPU_UTIL_STD_PCT:
+        training_votes.append(
+            f"low GPU utilization variance (std={features['std_gpu_util_pct']:.1f}) "
+            f"<= training ceiling {TRAINING_MAX_GPU_UTIL_STD_PCT}"
+        )
+    if features["mem_growth_mib_per_sample"] >= TRAINING_MIN_MEM_GROWTH_MIB_PER_SAMPLE:
+        training_votes.append(
+            f"memory growing {features['mem_growth_mib_per_sample']:.1f} MiB/sample "
+            f">= training threshold {TRAINING_MIN_MEM_GROWTH_MIB_PER_SAMPLE}"
+        )
+    if features["std_power_watts"] <= TRAINING_MAX_POWER_STD_WATTS:
+        training_votes.append(
+            f"low power-draw variance (std={features['std_power_watts']:.1f}W) "
+            f"<= training ceiling {TRAINING_MAX_POWER_STD_WATTS}W"
+        )
+
+    if features["avg_gpu_util_pct"] <= INFERENCE_MAX_AVG_GPU_UTIL_PCT:
+        inference_votes.append(
+            f"avg GPU utilization {features['avg_gpu_util_pct']:.1f}% "
+            f"<= inference ceiling {INFERENCE_MAX_AVG_GPU_UTIL_PCT}%"
+        )
+    if features["std_gpu_util_pct"] >= INFERENCE_MIN_GPU_UTIL_STD_PCT:
+        inference_votes.append(
+            f"bursty GPU utilization (std={features['std_gpu_util_pct']:.1f}) "
+            f">= inference threshold {INFERENCE_MIN_GPU_UTIL_STD_PCT}"
+        )
+    if features["mem_growth_mib_per_sample"] < TRAINING_MIN_MEM_GROWTH_MIB_PER_SAMPLE:
+        inference_votes.append(
+            f"flat memory usage ({features['mem_growth_mib_per_sample']:.1f} MiB/sample) "
+            f"< training threshold {TRAINING_MIN_MEM_GROWTH_MIB_PER_SAMPLE}"
+        )
+    if features["std_power_watts"] >= INFERENCE_MIN_POWER_STD_WATTS:
+        inference_votes.append(
+            f"bursty power draw (std={features['std_power_watts']:.1f}W) "
+            f">= inference threshold {INFERENCE_MIN_POWER_STD_WATTS}W"
+        )
+
+    total_votes = 4
+    if len(training_votes) > len(inference_votes):
+        workload_type = WorkloadType.TRAINING
+        reasons = training_votes
+        confidence = len(training_votes) / total_votes
+    elif len(inference_votes) > len(training_votes):
+        workload_type = WorkloadType.INFERENCE
+        reasons = inference_votes
+        confidence = len(inference_votes) / total_votes
+    else:
+        workload_type = WorkloadType.UNKNOWN
+        reasons = [
+            "training and inference signals tied "
+            f"({len(training_votes)} votes each) -- inconclusive"
+        ]
+        confidence = 0.5
+
+    return ClassificationResult(
+        workload_type=workload_type,
+        confidence=confidence,
+        gpu_index=gpu_index,
+        window_seconds=window_seconds,
+        sample_count=len(samples),
+        reasons=reasons,
+        features=features,
+    )

workloadtruth/cli.py

@@ -0,0 +1,217 @@
+"""WorkloadTruth CLI entry point."""
+
+from __future__ import annotations
+
+import json
+import sys
+import time
+from pathlib import Path
+
+import click
+
+from workloadtruth import __version__
+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
+from workloadtruth.types import ClassificationResult
+
+DEFAULT_LOG_PATH = Path("workloadtruth.log.jsonl")
+
+
+def _echo_result(result: ClassificationResult, as_json: bool) -> None:
+    if as_json:
+        click.echo(json.dumps(result.to_dict(), indent=2))
+        return
+    click.echo(f"workload_type : {result.workload_type.value}")
+    click.echo(f"confidence    : {result.confidence:.2f}")
+    click.echo(f"gpu_index     : {result.gpu_index}")
+    click.echo(f"samples       : {result.sample_count} over {result.window_seconds:.1f}s")
+    click.echo("reasons:")
+    for reason in result.reasons:
+        click.echo(f"  - {reason}")
+
+
+@click.group()
+@click.version_option(version=__version__, prog_name="workloadtruth")
+def main() -> None:
+    """Classify a GPU workload as INFERENCE, TRAINING, or IDLE from telemetry alone."""
+
+
+@main.command(name="classify")
+@click.option(
+    "--backend",
+    type=click.Choice(["synthetic", "nvml"]),
+    default="nvml",
+    show_default=True,
+    help="Telemetry source. 'synthetic' needs no GPU -- useful for trying the CLI.",
+)
+@click.option("--profile", default="training", help="Synthetic backend profile (synthetic only).")
+@click.option("--gpu-index", default=0, show_default=True, type=int)
+@click.option("--samples", default=10, show_default=True, type=int, help="Samples to collect.")
+@click.option(
+    "--interval", default=1.0, show_default=True, type=float, help="Seconds between samples."
+)
+@click.option(
+    "--experimental", is_flag=True, help="Use the experimental ML classifier (not yet available)."
+)
+@click.option("--json", "as_json", is_flag=True, help="Machine-readable JSON output.")
+def classify_cmd(
+    backend: str,
+    profile: str,
+    gpu_index: int,
+    samples: int,
+    interval: float,
+    experimental: bool,
+    as_json: bool,
+) -> None:
+    """One-shot classification of the current GPU workload."""
+    if experimental:
+        from workloadtruth.classifier.experimental import classify_experimental
+
+        classify_experimental()
+        return
+
+    backend_kwargs = {"profile": profile} if backend == "synthetic" else {}
+    tb = get_backend(backend, **backend_kwargs)
+    try:
+        collected = list(tb.sample_window(gpu_index, samples, interval))
+    finally:
+        tb.close()
+
+    result = classify(collected)
+    _echo_result(result, as_json)
+
+
+@main.command()
+@click.option(
+    "--backend",
+    type=click.Choice(["synthetic", "nvml"]),
+    default="nvml",
+    show_default=True,
+)
+@click.option("--profile", default="training", help="Synthetic backend profile (synthetic only).")
+@click.option("--gpu-index", default=0, show_default=True, type=int)
+@click.option(
+    "--interval", default=1.0, show_default=True, type=float, help="Seconds between samples."
+)
+@click.option(
+    "--window", default=10, show_default=True, type=int, help="Samples per classification window."
+)
+@click.option(
+    "--iterations",
+    default=0,
+    type=int,
+    help="Stop after N classification windows (0 = run forever).",
+)
+@click.option(
+    "--log-file",
+    default=str(DEFAULT_LOG_PATH),
+    show_default=True,
+    type=click.Path(path_type=Path),
+)
+@click.option("--json", "as_json", is_flag=True, help="Machine-readable JSON output per window.")
+def watch(
+    backend: str,
+    profile: str,
+    gpu_index: int,
+    interval: float,
+    window: int,
+    iterations: int,
+    log_file: Path,
+    as_json: bool,
+) -> None:
+    """Continuously classify and append hash-chained entries to the audit log."""
+    backend_kwargs = {"profile": profile} if backend == "synthetic" else {}
+    tb = get_backend(backend, **backend_kwargs)
+    iteration = 0
+    try:
+        while True:
+            collected = list(tb.sample_window(gpu_index, window, interval))
+            result = classify(collected)
+            prev = last_hash(log_file)
+            entry = build_entry(
+                timestamp=time.time(),
+                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(log_file, entry)
+            _echo_result(result, as_json)
+            iteration += 1
+            if iterations and iteration >= iterations:
+                break
+    finally:
+        tb.close()
+
+
+@main.command()
+@click.option(
+    "--trials", default=50, show_default=True, type=int, help="Trials per profile/evasion cell."
+)
+@click.option(
+    "--window", default=30, show_default=True, type=int, help="Samples per classification window."
+)
+@click.option("--json", "as_json", is_flag=True)
+def benchmark(trials: int, window: int, as_json: bool) -> None:
+    """Run the evasion-robustness benchmark against synthetic telemetry."""
+    from workloadtruth.benchmark import run_benchmark
+
+    report = run_benchmark(trials_per_cell=trials, window_size=window)
+    if as_json:
+        click.echo(json.dumps(report.to_dict(), indent=2))
+        return
+
+    click.echo("WorkloadTruth benchmark (synthetic telemetry -- see --json 'note' field)")
+    click.echo(f"clean accuracy   : {report.clean_accuracy:.1%}")
+    click.echo(f"evasion accuracy : {report.evasion_accuracy:.1%}")
+    click.echo("")
+    click.echo(f"{'profile':<12}{'evasion':<10}{'accuracy':<10}trials")
+    for cell in report.cells:
+        click.echo(f"{cell.profile:<12}{str(cell.evasion):<10}{cell.accuracy:<10.1%}{cell.trials}")
+
+
+@main.command(name="verify-log")
+@click.option(
+    "--log-file",
+    default=str(DEFAULT_LOG_PATH),
+    show_default=True,
+    type=click.Path(path_type=Path),
+)
+@click.option("--json", "as_json", is_flag=True)
+def verify_log(log_file: Path, as_json: bool) -> None:
+    """Verify the hash chain of a local audit log has not been tampered with."""
+    is_valid, message, count = verify_chain(log_file)
+    if as_json:
+        click.echo(json.dumps({"valid": is_valid, "message": message, "entries": count}, indent=2))
+    else:
+        status = "OK" if is_valid else "TAMPERED"
+        click.echo(f"[{status}] {message}")
+    if not is_valid:
+        sys.exit(1)
+
+
+@main.command()
+@click.option(
+    "--backend",
+    type=click.Choice(["synthetic", "nvml"]),
+    default="nvml",
+    show_default=True,
+)
+def mcp(backend: str) -> None:
+    """Start an MCP server exposing classify/benchmark/verify-log as agent tools."""
+    try:
+        from workloadtruth.mcp_server import run_server
+    except ImportError:
+        click.echo(
+            'The MCP server requires the "mcp" extra: pip install "workloadtruth-cli[mcp]"',
+            err=True,
+        )
+        sys.exit(1)
+    run_server(default_backend=backend)
+
+
+if __name__ == "__main__":
+    main()