feat(stats): add std_dev_case_length to LogStats and CLI output

Population standard deviation of case lengths gives a direct measure of
process variability: a log where every case has the same length scores
0, while one with high variance scores proportionally higher. The value
is included in the JSON emitted by 'pm-bench stats' alongside mean and
median, completing the five-number-summary picture.

Uses statistics.pstdev (population std dev) consistent with fmean and
median already in summarize(). Empty or single-case logs return 0.0.

Author: protosphinx

pm_bench/cli.py

@@ -392,6 +392,7 @@ def stats(name: str, top_n: int) -> None:
                 "latest": s.latest.isoformat() if s.latest else None,
                 "mean_case_length": s.mean_case_length,
                 "median_case_length": s.median_case_length,
+                "std_dev_case_length": s.std_dev_case_length,
                 "min_case_length": s.min_case_length,
                 "max_case_length": s.max_case_length,
                 "top_activities": [

pm_bench/stats.py

@@ -2,9 +2,9 @@
 
 Useful when inspecting a new dataset - n_cases, n_events, distinct
 activity count, time span, top-N most-frequent activities and
-transitions, mean / median / min / max case length. Pure CPython; runs
-in the same process as the rest of pm-bench so it works on
-`synthetic-toy`, any CSV path, and (eventually) any cached BPI log.
+transitions, mean / median / min / max / std-dev case length. Pure
+CPython; runs in the same process as the rest of pm-bench so it works
+on `synthetic-toy`, any CSV path, and (eventually) any cached BPI log.
 """
 from __future__ import annotations
 
@@ -27,6 +27,7 @@ class LogStats:
     latest: datetime | None
     mean_case_length: float
     median_case_length: float
+    std_dev_case_length: float
     min_case_length: int
     max_case_length: int
     top_activities: list[tuple[Activity, int]]
@@ -68,6 +69,7 @@ def summarize(events: Iterable[Event], *, top_n: int = 10) -> LogStats:
     n_cases = len(by_case)
     mean_len = statistics.fmean(case_lengths) if case_lengths else 0.0
     median_len = statistics.median(case_lengths) if case_lengths else 0.0
+    std_dev_len = statistics.pstdev(case_lengths) if case_lengths else 0.0
     min_len = min(case_lengths) if case_lengths else 0
     max_len = max(case_lengths) if case_lengths else 0
 
@@ -80,6 +82,7 @@ def summarize(events: Iterable[Event], *, top_n: int = 10) -> LogStats:
         latest=latest,
         mean_case_length=mean_len,
         median_case_length=median_len,
+        std_dev_case_length=std_dev_len,
         min_case_length=min_len,
         max_case_length=max_len,
         top_activities=_top_n_sorted(activity_counts, top_n),

tests/test_stats.py

@@ -115,3 +115,49 @@ def test_cli_stats_synthetic_toy() -> None:
     assert len(data["top_activities"]) == 3
     assert "min_case_length" in data
     assert "max_case_length" in data
+
+
+def test_summarize_std_dev_empty_log() -> None:
+    s = summarize([])
+    assert s.std_dev_case_length == 0.0
+
+
+def test_summarize_std_dev_single_case() -> None:
+    ts = dt.datetime(2024, 6, 1)
+    s = summarize([("c1", "a", ts), ("c1", "b", ts + dt.timedelta(hours=1))])
+    # Only one case; population std dev of [2] is 0.
+    assert s.std_dev_case_length == 0.0
+
+
+def test_summarize_std_dev_uniform_cases() -> None:
+    # Three cases, each with exactly 2 events: std dev must be 0.
+    base = dt.datetime(2024, 1, 1)
+    events = [
+        ("c1", "a", base),
+        ("c1", "b", base + dt.timedelta(hours=1)),
+        ("c2", "a", base + dt.timedelta(days=1)),
+        ("c2", "b", base + dt.timedelta(days=1, hours=1)),
+        ("c3", "a", base + dt.timedelta(days=2)),
+        ("c3", "b", base + dt.timedelta(days=2, hours=1)),
+    ]
+    s = summarize(events)
+    assert s.std_dev_case_length == 0.0
+
+
+def test_summarize_std_dev_case_length_value() -> None:
+    import statistics
+
+    # _events() gives case lengths [3, 2, 1] (order stable inside cases).
+    s = summarize(_events())
+    expected = statistics.pstdev([3, 2, 1])
+    assert abs(s.std_dev_case_length - expected) < 1e-9
+
+
+def test_cli_stats_std_dev_present() -> None:
+    runner = CliRunner()
+    r = runner.invoke(main, ["stats", "synthetic-toy"])
+    assert r.exit_code == 0, r.output
+    data = json.loads(r.output)
+    assert "std_dev_case_length" in data
+    assert isinstance(data["std_dev_case_length"], float)
+    assert data["std_dev_case_length"] >= 0.0