margin 0.9.16__tar.gz → 0.9.18__tar.gz

{margin-0.9.16/margin.egg-info → margin-0.9.18}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: margin
-Version: 0.9.16
+Version: 0.9.18
 Summary: Typed health classification, uncertainty algebra, and correction auditing for any system that measures things and needs to explain what happened.
 Author: Cope Labs LLC
 License: MIT

{margin-0.9.16 → margin-0.9.18}/margin/fingerprint.py

@@ -87,11 +87,16 @@ class Fingerprint(dict):
         ``method="trimmed"``  — 10% trimmed mean
         ``method="mean"``     — plain mean (same as ``fp[component]["mean"]``)
 
-        Falls back to ``fp[component]["mean"]`` when no raw values are stored.
+        When no raw values are stored, checks for pre-computed ``"median"`` in
+        the stats dict (present when fingerprint came from ``Monitor.fingerprint()``),
+        then falls back to ``"mean"``.
         """
         vals = self._values.get(component)
         if not vals:
-            return self.get(component, {}).get("mean", 0.0)
+            stats = self.get(component, {})
+            if method == "median":
+                return stats.get("median", stats.get("mean", 0.0))
+            return stats.get("mean", 0.0)
         if method == "median":
             return _percentile(vals, 50)
         if method == "trimmed":
@@ -103,32 +108,49 @@ class Fingerprint(dict):
         """
         Return the p-th percentile (0–100) of observed values for ``component``.
 
-        Falls back to the stored mean when no raw values are available.
+        When no raw values are stored, checks for pre-computed ``"q25"`` / ``"q75"`` /
+        ``"median"`` in the stats dict (present when fingerprint came from
+        ``Monitor.fingerprint()``), then falls back to ``"mean"``.
         """
         vals = self._values.get(component)
         if not vals:
-            return self.get(component, {}).get("mean", 0.0)
+            stats = self.get(component, {})
+            if p == 25 and "q25" in stats:
+                return stats["q25"]
+            if p == 75 and "q75" in stats:
+                return stats["q75"]
+            if p == 50 and "median" in stats:
+                return stats["median"]
+            return stats.get("mean", 0.0)
         return _percentile(vals, p)
 
     def sigma(self, component: str, value: float) -> float:
         """
-        Normalize ``value`` against the fingerprint's empirical mean.
+        Z-score of ``value`` against the fingerprint's empirical distribution.
 
-        Returns ``(value − mean) / |mean|``.
+        Returns ``(value − mean) / std``  (standard z-score).
 
-        Positive = above session baseline; negative = below.  Used to
-        convert a raw domain measurement into a cross-session comparable
-        signal before passing it to ``Controller.step()``.
+        Using ``std`` as denominator is correct for cross-session normalization.
+        ``|mean|`` would only be appropriate when the coefficient of variation
+        (std/|mean|) is small; for high-CV components (e.g. ``std=0.498``,
+        ``mean=0.070``, CV=7.1) it amplifies by 7×, turning a normal ±0.07
+        swing into ±1.0 and saturating the controller.
 
-        Returns ``value`` unchanged when the stored mean is zero
-        (no finite normalization is possible).
+        Falls back to ``(value − mean) / |mean|`` when ``std`` is zero (constant
+        window or not yet stored), and returns ``value`` unchanged when both
+        ``mean`` and ``std`` are zero.
 
         Example::
 
             metric = fp.sigma("recovery_ratio", cq.recovery_ratio)
             alpha, reason = ctrl.step(alpha, metric)
         """
-        mean = self.get(component, {}).get("mean", 0.0)
+        stats = self.get(component, {})
+        mean = stats.get("mean", 0.0)
+        std = stats.get("std", 0.0)
+        if std != 0.0:
+            return (value - mean) / std
+        # std=0: constant distribution — fall back to relative deviation
         if mean == 0.0:
             return value
         return (value - mean) / abs(mean)

{margin-0.9.16 → margin-0.9.18}/margin/streaming.py

@@ -64,7 +64,7 @@ from .confidence import Confidence
 from .health import Health, Thresholds, classify
 from .observation import Observation, Expression
 from .provenance import ProvenanceGraph
-from .fingerprint import Fingerprint
+from .fingerprint import Fingerprint, _percentile as _fp_percentile
 from .drift import (
     DriftState, DriftDirection, DriftClassification,
     classify_drift,
@@ -606,6 +606,9 @@ class Monitor:
                 "std": std,
                 "n": n,
                 "trend": dc.state.value if dc is not None else "UNKNOWN",
+                "median": _fp_percentile(values, 50),
+                "q25": _fp_percentile(values, 25),
+                "q75": _fp_percentile(values, 75),
             }
             raw_values[name] = values
         return Fingerprint(stats=stats, values=raw_values)

{margin-0.9.16 → margin-0.9.18/margin.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: margin
-Version: 0.9.16
+Version: 0.9.18
 Summary: Typed health classification, uncertainty algebra, and correction auditing for any system that measures things and needs to explain what happened.
 Author: Cope Labs LLC
 License: MIT

{margin-0.9.16 → margin-0.9.18}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "margin"
-version = "0.9.16"
+version = "0.9.18"
 description = "Typed health classification, uncertainty algebra, and correction auditing for any system that measures things and needs to explain what happened."
 readme = "README.md"
 license = {text = "MIT"}

{margin-0.9.16 → margin-0.9.18}/tests/test_controller.py

@@ -552,14 +552,100 @@ class TestFingerprintSigma:
 
     def test_negative_mean(self):
         fp = Fingerprint(stats={"rr": {"mean": -2.0, "std": 0.5, "n": 10, "trend": "STABLE"}})
-        # (value - mean) / |mean| = (-1.0 - (-2.0)) / 2.0 = 0.5
-        assert fp.sigma("rr", -1.0) == pytest.approx(0.5)
+        # z-score: (value - mean) / std = (-1.0 - (-2.0)) / 0.5 = 2.0
+        assert fp.sigma("rr", -1.0) == pytest.approx(2.0)
 
     def test_missing_component_returns_value(self):
         fp = _make_fp([1.0] * 10)
         # missing → mean=0.0 → returns value unchanged
         assert fp.sigma("missing", 0.7) == pytest.approx(0.7)
 
+    def test_uses_std_not_mean_as_denominator(self):
+        # Regression: Build #29 failure — high-CV component (std=0.498, mean=0.070)
+        # Old formula: (value - mean) / |mean| = 0.07 / 0.07 = 1.0 (7× amplification)
+        # New formula: (value - mean) / std   = 0.07 / 0.498 ≈ 0.141 (sensible z-score)
+        fp = Fingerprint(stats={"rr": {"mean": 0.070, "std": 0.498, "n": 98}})
+        result = fp.sigma("rr", 0.14)
+        assert result == pytest.approx((0.14 - 0.070) / 0.498, rel=1e-4)  # z-score
+        assert abs(result) < 0.2  # not ±1.0 (the bang-bang range)
+
+    def test_std_zero_falls_back_to_mean_relative(self):
+        # Constant distribution: std=0 → fall back to (value-mean)/|mean|
+        fp = Fingerprint(stats={"rr": {"mean": 1.0, "std": 0.0, "n": 5}})
+        assert fp.sigma("rr", 1.5) == pytest.approx(0.5)  # (1.5-1.0)/1.0
+
+
+class TestFingerprintPrecomputedPercentiles:
+    """Fingerprints from Monitor.fingerprint() now include median/q25/q75.
+    percentile() and robust_target() must use them when no raw values stored."""
+
+    def test_monitor_fingerprint_includes_median(self):
+        monitor = _make_monitor(20)
+        fp = monitor.fingerprint()
+        assert "median" in fp["alpha"]
+        assert "q25" in fp["alpha"]
+        assert "q75" in fp["alpha"]
+
+    def test_robust_sigma_live_after_serialization(self):
+        # Simulate the Build #29 scenario:
+        # Session 1 fingerprint saved as JSON, loaded in Session 2 — no raw values.
+        monitor = _make_monitor(30)
+        fp_live = monitor.fingerprint()
+        # Round-trip through JSON (loses raw values, keeps precomputed percentiles)
+        import json
+        fp_reloaded = Fingerprint.from_dict(json.loads(json.dumps(fp_live)))
+        # robust_sigma should differ from sigma (IQR != 0, median != mean generally)
+        # At minimum, it must not crash and must not return 0.0 for a nonzero input
+        result = fp_reloaded.robust_sigma("alpha", 0.55)
+        assert isinstance(result, float)
+
+    def test_robust_sigma_uses_precomputed_iqr(self):
+        # Construct fingerprint with known median/q25/q75
+        fp = Fingerprint(stats={"rr": {
+            "mean": 0.070, "std": 0.498, "n": 98, "trend": "DRIFTING",
+            "median": 0.050, "q25": 0.020, "q75": 0.120,
+        }})
+        # IQR = 0.120 - 0.020 = 0.100
+        # robust_sigma(0.14) = (0.14 - 0.050) / 0.100 = 0.9
+        assert fp.robust_sigma("rr", 0.14) == pytest.approx(0.9)
+
+    def test_robust_sigma_differs_from_mean_based(self):
+        # When median != mean (skewed distribution), the two should differ
+        fp = Fingerprint(stats={"rr": {
+            "mean": 0.070, "std": 0.498, "n": 98, "trend": "DRIFTING",
+            "median": 0.050, "q25": 0.020, "q75": 0.120,
+        }})
+        assert fp.robust_sigma("rr", 0.14) != pytest.approx(fp.sigma("rr", 0.14))
+
+    def test_regression_build29_scenario(self):
+        # Exact values from the user's Session 1 meta.json
+        fp = Fingerprint(stats={"recovery_ratio": {
+            "mean": 0.070, "std": 0.498, "n": 98, "trend": "DRIFTING",
+            "median": 0.050, "q25": 0.020, "q75": 0.120,
+        }})
+        r = fp.robust_sigma("recovery_ratio", 0.14)
+        # Previously returned 1.0 (mean-based fallback); now uses IQR
+        assert r == pytest.approx(0.9)
+        mean_based = fp.sigma("recovery_ratio", 0.14)
+        assert r != pytest.approx(mean_based)
+
+    def test_percentile_uses_precomputed_q25(self):
+        fp = Fingerprint(stats={"rr": {
+            "mean": 1.0, "std": 0.1, "n": 10, "trend": "STABLE",
+            "median": 1.0, "q25": 0.8, "q75": 1.2,
+        }})
+        assert fp.percentile("rr", 25) == pytest.approx(0.8)
+        assert fp.percentile("rr", 75) == pytest.approx(1.2)
+        assert fp.percentile("rr", 50) == pytest.approx(1.0)
+
+    def test_percentile_fallback_to_mean_for_other_p(self):
+        # Only 25/50/75 are pre-computed; other p falls back to mean
+        fp = Fingerprint(stats={"rr": {
+            "mean": 1.0, "std": 0.1, "n": 10, "trend": "STABLE",
+            "median": 1.0, "q25": 0.8, "q75": 1.2,
+        }})
+        assert fp.percentile("rr", 10) == pytest.approx(1.0)  # falls back to mean
+
 
 class TestFingerprintRobustSigma:
     def test_median_centered(self):