margin 0.9.3__tar.gz → 0.9.5__tar.gz

{margin-0.9.3/margin.egg-info → margin-0.9.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: margin
-Version: 0.9.3
+Version: 0.9.5
 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.3 → margin-0.9.5}/margin/__init__.py

@@ -82,6 +82,7 @@ from .contract import (
     HealthTarget, ReachHealth, SustainHealth,
     RecoveryThreshold, NoHarmful,
     ContractResult, Contract,
+    contract_term_from_dict,
 )
 
 # Correlation
@@ -164,7 +165,7 @@ __all__ = [
     "TermStatus", "TermResult", "ContractTerm",
     "HealthTarget", "ReachHealth", "SustainHealth",
     "RecoveryThreshold", "NoHarmful",
-    "ContractResult", "Contract",
+    "ContractResult", "Contract", "contract_term_from_dict",
     # Correlation
     "Correlation", "CorrelationMatrix",
     "correlate_pair", "correlate", "correlate_from_ledger",

{margin-0.9.3 → margin-0.9.5}/margin/calibrate.py

@@ -157,10 +157,10 @@ def calibrate_many(
     use_std: bool = False,
     intact_std_multiplier: float = 1.5,
     ablated_std_multiplier: float = 3.0,
-) -> tuple[dict[str, float], dict[str, Thresholds]]:
+    return_parser: bool = False,
+):
     """
-    Calibrate multiple components at once. Returns (baselines, thresholds)
-    ready to pass directly to Parser().
+    Calibrate multiple components at once.
 
     Args:
         component_values:        {name: [healthy_measurements]}
@@ -171,12 +171,14 @@ def calibrate_many(
         use_std:                 if True, use std-based thresholds (see calibrate())
         intact_std_multiplier:   std deviations for intact threshold (std mode)
         ablated_std_multiplier:  std deviations for ablated threshold (std mode)
+        return_parser:           if True, return a ready-to-use Parser instead of the raw tuple
 
     Returns:
-        (baselines_dict, thresholds_dict) suitable for:
+        When return_parser=False (default): (baselines_dict, thresholds_dict) suitable for:
             Parser(baselines=baselines_dict,
                    thresholds=first_threshold,
                    component_thresholds=thresholds_dict)
+        When return_parser=True: a Parser with baselines and per-component thresholds set
     """
     polarities = polarities or {}
     baselines = {}
@@ -193,6 +195,18 @@ def calibrate_many(
         baselines[name] = result.baseline
         thresholds[name] = result.thresholds
 
+    if return_parser:
+        names = list(thresholds.keys())
+        if not names:
+            raise ValueError("No components to calibrate")
+        default_thresholds = thresholds[names[0]]
+        component_thresholds = {n: t for n, t in thresholds.items() if n != names[0]}
+        return Parser(
+            baselines=baselines,
+            thresholds=default_thresholds,
+            component_thresholds=component_thresholds,
+        )
+
     return baselines, thresholds
 
 
@@ -298,7 +312,7 @@ def recalibrate_parser(
     components: Optional[list[str]] = None,
     intact_fraction: float = 0.70,
     ablated_fraction: float = 0.30,
-    active_min: float = 0.05,
+    active_min: Optional[float] = None,
     use_std: bool = False,
     intact_std_multiplier: float = 1.5,
     ablated_std_multiplier: float = 3.0,
@@ -324,8 +338,8 @@ def recalibrate_parser(
                                  all components in new_healthy_data are recalibrated
         intact_fraction:         fraction of baseline for intact threshold (fraction mode)
         ablated_fraction:        fraction of baseline for ablated threshold (fraction mode)
-        active_min:              inherited from existing parser thresholds; pass only
-                                 to override for recalibrated components
+        active_min:              None (default) inherits from each component's existing
+                                 threshold; pass an explicit float to override
         use_std:                 if True, use std-based thresholds (see calibrate())
         intact_std_multiplier:   std deviations for intact threshold (std mode)
         ablated_std_multiplier:  std deviations for ablated threshold (std mode)
@@ -359,8 +373,8 @@ def recalibrate_parser(
         # Resolve polarity: explicit override → existing parser polarity → True
         existing_t = parser.component_thresholds.get(name) or parser.thresholds
         hib = polarities.get(name, existing_t.higher_is_better)
-        # Inherit active_min from existing thresholds unless caller overrides
-        component_active_min = existing_t.active_min if active_min == 0.05 else active_min
+        # Inherit active_min from existing thresholds unless caller provides an explicit override
+        component_active_min = existing_t.active_min if active_min is None else active_min
         result = calibrate(
             vals, hib, intact_fraction, ablated_fraction, component_active_min,
             use_std=use_std,

{margin-0.9.3 → margin-0.9.5}/margin/contract.py

@@ -232,6 +232,38 @@ class NoHarmful(ContractTerm):
         return {"type": "no_harmful", "name": self.name, "over_steps": self.over_steps}
 
 
+_TERM_TYPES: dict = {
+    "health_target": lambda d: HealthTarget(
+        name=d["name"], component=d["component"],
+        target=Health(d["target"]), or_better=d.get("or_better", True),
+    ),
+    "reach_health": lambda d: ReachHealth(
+        name=d["name"], component=d["component"],
+        target=Health(d["target"]), within_steps=d["within_steps"],
+    ),
+    "sustain_health": lambda d: SustainHealth(
+        name=d["name"], component=d["component"],
+        target=Health(d["target"]), for_steps=d["for_steps"],
+        or_better=d.get("or_better", True),
+    ),
+    "recovery_threshold": lambda d: RecoveryThreshold(
+        name=d["name"], min_recovery=d["min_recovery"], over_steps=d["over_steps"],
+    ),
+    "no_harmful": lambda d: NoHarmful(
+        name=d["name"], over_steps=d["over_steps"],
+    ),
+}
+
+
+def contract_term_from_dict(d: dict) -> ContractTerm:
+    """Deserialize a ContractTerm subclass from a dict produced by its to_dict()."""
+    term_type = d.get("type")
+    if term_type not in _TERM_TYPES:
+        raise ValueError(f"Unknown contract term type: {term_type!r}. "
+                         f"Expected one of: {list(_TERM_TYPES)}")
+    return _TERM_TYPES[term_type](d)
+
+
 # -----------------------------------------------------------------------
 # Contract — a set of terms evaluated together
 # -----------------------------------------------------------------------

{margin-0.9.3 → margin-0.9.5}/margin/loop.py

@@ -50,7 +50,9 @@ class StepResult:
     @property
     def acted(self) -> bool:
         """True if a real correction was produced (not NOOP, not escalation)."""
-        return self.correction is not None and self.correction.is_active()
+        if self.correction is not None and self.correction.is_active():
+            return True
+        return any(c.is_active() for c in self.corrections)
 
     @property
     def escalated(self) -> bool:

{margin-0.9.3 → margin-0.9.5}/margin/streaming.py

@@ -34,6 +34,26 @@ class WindowConfig:
     anomaly: Optional[int] = None
     correlation: Optional[int] = None
 
+    def to_dict(self) -> dict:
+        """Serialize to plain dict; omits None fields."""
+        d: dict = {}
+        if self.drift is not None:
+            d["drift"] = self.drift
+        if self.anomaly is not None:
+            d["anomaly"] = self.anomaly
+        if self.correlation is not None:
+            d["correlation"] = self.correlation
+        return d
+
+    @classmethod
+    def from_dict(cls, d: dict) -> 'WindowConfig':
+        """Deserialize from a plain dict produced by to_dict()."""
+        return cls(
+            drift=d.get("drift"),
+            anomaly=d.get("anomaly"),
+            correlation=d.get("correlation"),
+        )
+
 from .confidence import Confidence
 from .health import Health, Thresholds, classify
 from .observation import Observation, Expression
@@ -478,18 +498,23 @@ class Monitor:
         return self._step
 
     def status(self) -> dict:
-        """Full snapshot: health + drift + anomaly + correlations."""
+        """Full snapshot: health + drift + anomaly + correlations.
+
+        Keys are always present; disabled features or no-data trackers
+        return empty dicts so callers can index without key-existence checks.
+        """
         d: dict = {
             "step": self._step,
             "expression": self._expression.to_dict() if self._expression else None,
+            "drift": {},
+            "anomaly": {},
+            "correlations": {},
         }
         if "drift" in self.features:
-            d["drift"] = {}
             for name, tracker in self._drift_trackers.items():
                 if tracker.classification:
                     d["drift"][name] = tracker.classification.to_dict()
         if "anomaly" in self.features:
-            d["anomaly"] = {}
             for name, tracker in self._anomaly_trackers.items():
                 if tracker.classification:
                     d["anomaly"][name] = tracker.classification.to_dict()

{margin-0.9.3 → margin-0.9.5/margin.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: margin
-Version: 0.9.3
+Version: 0.9.5
 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.3 → margin-0.9.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "margin"
-version = "0.9.3"
+version = "0.9.5"
 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.3 → margin-0.9.5}/tests/test_calibrate.py

@@ -176,3 +176,78 @@ class TestNeedsRecalibrationMany:
         flags = needs_recalibration_many(cal, recent)
         assert flags["cpu"] is True
         assert flags["mem"] is False
+
+
+class TestCalibrateManyReturnParser:
+    def test_return_parser_gives_parser(self):
+        from margin.observation import Parser
+        result = calibrate_many(
+            {"rps": [90.0, 100.0, 110.0], "latency": [48.0, 50.0, 52.0]},
+            polarities={"latency": False},
+            return_parser=True,
+        )
+        assert isinstance(result, Parser)
+
+    def test_return_parser_classifies_correctly(self):
+        result = calibrate_many(
+            {"rps": [100.0] * 10, "latency": [50.0] * 10},
+            polarities={"latency": False},
+            return_parser=True,
+        )
+        from margin.health import Health
+        expr = result.parse({"rps": 95.0, "latency": 52.0})
+        assert expr.health_of("rps") == Health.INTACT
+        assert expr.health_of("latency") == Health.INTACT
+
+    def test_return_parser_false_gives_tuple(self):
+        result = calibrate_many({"rps": [100.0] * 5})
+        assert isinstance(result, tuple)
+        assert len(result) == 2
+
+    def test_return_parser_empty_raises(self):
+        import pytest
+        with pytest.raises(ValueError):
+            calibrate_many({}, return_parser=True)
+
+
+class TestRecalibrateParserActiveMin:
+    def test_none_inherits_from_existing_parser(self):
+        from margin.calibrate import recalibrate_parser
+        # Parser with non-default active_min
+        parser = parser_from_calibration({"cpu": [100.0] * 5})
+        # Manually set a custom active_min on the thresholds
+        import dataclasses
+        custom_thresh = dataclasses.replace(parser.thresholds, active_min=0.15)
+        parser2 = parser.__class__(
+            baselines=parser.baselines,
+            thresholds=custom_thresh,
+            component_thresholds=parser.component_thresholds,
+        )
+        new_parser, _ = recalibrate_parser(parser2, {"cpu": [110.0] * 5})
+        # active_min should be inherited as 0.15, not the old 0.05 sentinel
+        result_thresh = new_parser.component_thresholds.get("cpu") or new_parser.thresholds
+        assert result_thresh.active_min == pytest.approx(0.15)
+
+    def test_explicit_active_min_overrides_existing(self):
+        from margin.calibrate import recalibrate_parser
+        parser = parser_from_calibration({"cpu": [100.0] * 5})
+        new_parser, _ = recalibrate_parser(parser, {"cpu": [110.0] * 5}, active_min=0.20)
+        result_thresh = new_parser.component_thresholds.get("cpu") or new_parser.thresholds
+        assert result_thresh.active_min == pytest.approx(0.20)
+
+    def test_explicit_005_is_not_swallowed(self):
+        # Regression: before fix, active_min=0.05 was sentinel for "inherit"
+        # so an explicit 0.05 would be silently replaced by existing parser's value
+        from margin.calibrate import recalibrate_parser
+        import dataclasses
+        parser = parser_from_calibration({"cpu": [100.0] * 5})
+        custom_thresh = dataclasses.replace(parser.thresholds, active_min=0.30)
+        parser2 = parser.__class__(
+            baselines=parser.baselines,
+            thresholds=custom_thresh,
+            component_thresholds=parser.component_thresholds,
+        )
+        # Explicitly pass 0.05 — should get 0.05, not 0.30
+        new_parser, _ = recalibrate_parser(parser2, {"cpu": [110.0] * 5}, active_min=0.05)
+        result_thresh = new_parser.component_thresholds.get("cpu") or new_parser.thresholds
+        assert result_thresh.active_min == pytest.approx(0.05)

{margin-0.9.3 → margin-0.9.5}/tests/test_contract.py

@@ -222,3 +222,53 @@ class TestContract:
         d = r.to_dict()
         assert d["all_met"] is True
         assert d["n_met"] == 1
+
+
+class TestContractTermFromDict:
+    def test_health_target_roundtrip(self):
+        from margin import contract_term_from_dict
+        from margin import HealthTarget
+        t = HealthTarget(name="t1", component="cpu", target=Health.INTACT)
+        t2 = contract_term_from_dict(t.to_dict())
+        assert isinstance(t2, HealthTarget)
+        assert t2.name == "t1"
+        assert t2.component == "cpu"
+        assert t2.target == Health.INTACT
+        assert t2.or_better is True
+
+    def test_reach_health_roundtrip(self):
+        from margin import contract_term_from_dict
+        from margin import ReachHealth
+        t = ReachHealth(name="r1", component="mem", target=Health.DEGRADED, within_steps=10)
+        t2 = contract_term_from_dict(t.to_dict())
+        assert isinstance(t2, ReachHealth)
+        assert t2.within_steps == 10
+
+    def test_sustain_health_roundtrip(self):
+        from margin import contract_term_from_dict
+        from margin import SustainHealth
+        t = SustainHealth(name="s1", component="cpu", target=Health.INTACT,
+                          for_steps=5, or_better=False)
+        t2 = contract_term_from_dict(t.to_dict())
+        assert isinstance(t2, SustainHealth)
+        assert t2.for_steps == 5
+        assert t2.or_better is False
+
+    def test_recovery_threshold_roundtrip(self):
+        from margin import contract_term_from_dict, RecoveryThreshold
+        t = RecoveryThreshold(name="rt", min_recovery=0.8, over_steps=20)
+        t2 = contract_term_from_dict(t.to_dict())
+        assert isinstance(t2, RecoveryThreshold)
+        assert t2.min_recovery == pytest.approx(0.8)
+
+    def test_no_harmful_roundtrip(self):
+        from margin import contract_term_from_dict, NoHarmful
+        t = NoHarmful(name="nh", over_steps=15)
+        t2 = contract_term_from_dict(t.to_dict())
+        assert isinstance(t2, NoHarmful)
+        assert t2.over_steps == 15
+
+    def test_unknown_type_raises(self):
+        from margin import contract_term_from_dict
+        with pytest.raises(ValueError, match="Unknown"):
+            contract_term_from_dict({"type": "nonexistent", "name": "x"})

{margin-0.9.3 → margin-0.9.5}/tests/test_policy_trace.py

@@ -1,4 +1,5 @@
 import pytest
+from margin.loop import step
 from margin.policy.core import Policy, PolicyRule, Action, Constraint, Escalation, EscalationLevel
 from margin.policy.trace import trace_evaluate, trace_backtest, DecisionTrace
 from margin.observation import Observation, Expression, Op
@@ -140,9 +141,6 @@ class TestBacktestProposedBy:
 
 class TestMultiRule:
     def _make_multi_policy(self):
-        from margin.policy.core import Policy, PolicyRule, Action
-        from margin.observation import Op
-        from margin.predicates import any_health, any_degraded
         return Policy(
             name="multi",
             multi_rule=True,
@@ -169,9 +167,6 @@ class TestMultiRule:
     def test_trace_always_has_all_matched_results(self):
         # trace_evaluate always populates dt.results for all matches;
         # multi_rule only gates StepResult.corrections in step()
-        from margin.policy.core import Policy, PolicyRule, Action
-        from margin.observation import Op
-        from margin.predicates import any_degraded
         policy = Policy(
             name="single",
             multi_rule=False,
@@ -191,7 +186,6 @@ class TestMultiRule:
         assert d["multi_rule"] is True
 
     def test_multi_rule_default_is_false(self):
-        from margin.policy.core import Policy
         policy = Policy(name="p", rules=[])
         assert policy.multi_rule is False
         assert policy.to_dict()["multi_rule"] is False
@@ -199,11 +193,6 @@ class TestMultiRule:
 
 class TestStepResultCorrections:
     def test_step_corrections_populated_multi_rule(self):
-        from margin.loop import step
-        from margin.policy.core import Policy, PolicyRule, Action
-        from margin.observation import Op
-        from margin.predicates import any_degraded
-
         policy = Policy(
             name="multi",
             multi_rule=True,
@@ -216,11 +205,6 @@ class TestStepResultCorrections:
         assert len(result.corrections) >= 1
 
     def test_step_corrections_empty_single_rule(self):
-        from margin.loop import step
-        from margin.policy.core import Policy, PolicyRule, Action
-        from margin.observation import Op
-        from margin.predicates import any_degraded
-
         policy = Policy(
             name="single",
             multi_rule=False,
@@ -229,3 +213,42 @@ class TestStepResultCorrections:
         result = step(_expr(_obs("x", Health.DEGRADED)), policy)
         # multi_rule=False → corrections list is empty (only .correction populated)
         assert result.corrections == []
+
+
+class TestStepResultActed:
+    def test_acted_true_when_correction_active(self):
+        policy = Policy(
+            name="p", multi_rule=False,
+            rules=[PolicyRule("r", any_degraded(), Action(target="*", op=Op.RESTORE, alpha=0.5))],
+        )
+        result = step(_expr(_obs("x", Health.DEGRADED)), policy)
+        assert result.acted is True
+
+    def test_acted_false_on_noop(self):
+        from margin.predicates import any_health
+        policy = Policy(
+            name="p", multi_rule=False,
+            rules=[PolicyRule("r", any_health(Health.DEGRADED), Action(target="*", op=Op.NOOP))],
+        )
+        result = step(_expr(_obs("x", Health.DEGRADED)), policy)
+        assert result.acted is False
+
+    def test_acted_true_when_correction_in_multi_rule_corrections_list(self):
+        # First result is Escalation (no min_alpha satisfied), second is a Correction
+        # multi_rule=True → both fire; acted should see the Correction in .corrections
+        policy = Policy(
+            name="p", multi_rule=True,
+            rules=[
+                PolicyRule("esc", any_degraded(),
+                           Action(target="*", op=Op.RESTORE, alpha=0.1),
+                           constraint=Constraint(min_alpha=0.9),  # suppressed → escalation
+                           priority=10),
+                PolicyRule("fix", any_degraded(),
+                           Action(target="*", op=Op.RESTORE, alpha=0.5),
+                           priority=5),
+            ],
+        )
+        result = step(_expr(_obs("x", Health.DEGRADED, 10.0)), policy)
+        # .corrections contains the Correction from "fix"
+        assert any(c.is_active() for c in result.corrections)
+        assert result.acted is True

{margin-0.9.3 → margin-0.9.5}/tests/test_streaming.py

@@ -6,6 +6,7 @@ from margin import (
     Observation, Health, Confidence, Thresholds, Parser,
     DriftState, DriftDirection, AnomalyState,
     DriftTracker, AnomalyTracker, CorrelationTracker, Monitor,
+    WindowConfig,
 )
 
 
@@ -330,15 +331,16 @@ class TestMonitorFeatures:
         m = Monitor(self._parser(), features={"health", "drift"})
         assert isinstance(m.features, frozenset)
 
-    def test_status_omits_disabled_feature_keys(self):
+    def test_status_always_has_drift_anomaly_correlations_keys(self):
         m = Monitor(self._parser(), features={"health"})
         for i in range(5):
             m.update({"cpu": 50.0 - i, "mem": 70.0},
                      now=t0 + timedelta(seconds=i * 60))
         s = m.status()
-        # drift disabled → "drift" key absent
-        assert "drift" not in s
-        assert "anomaly" not in s
+        # Keys always present — empty dict when feature disabled or no data yet
+        assert "drift" in s and s["drift"] == {}
+        assert "anomaly" in s and s["anomaly"] == {}
+        assert "correlations" in s and s["correlations"] == {}
 
     def test_repr_shows_features_when_partial(self):
         m = Monitor(self._parser(), features={"health", "drift"})
@@ -405,3 +407,44 @@ class TestMonitorResetAnomalyReference:
         m = Monitor(self._parser(), features={"health", "drift"})
         # Should not raise even though anomaly trackers don't exist
         m.reset_anomaly_reference()
+
+
+# -----------------------------------------------------------------------
+# WindowConfig serialization
+# -----------------------------------------------------------------------
+
+class TestWindowConfigSerialization:
+    def test_to_dict_full(self):
+        wc = WindowConfig(drift=10, anomaly=40, correlation=100)
+        d = wc.to_dict()
+        assert d == {"drift": 10, "anomaly": 40, "correlation": 100}
+
+    def test_to_dict_partial(self):
+        wc = WindowConfig(drift=10)
+        d = wc.to_dict()
+        assert d == {"drift": 10}
+        assert "anomaly" not in d
+        assert "correlation" not in d
+
+    def test_to_dict_empty(self):
+        wc = WindowConfig()
+        assert wc.to_dict() == {}
+
+    def test_from_dict_roundtrip(self):
+        wc = WindowConfig(drift=10, anomaly=40, correlation=100)
+        wc2 = WindowConfig.from_dict(wc.to_dict())
+        assert wc2.drift == 10
+        assert wc2.anomaly == 40
+        assert wc2.correlation == 100
+
+    def test_from_dict_partial(self):
+        wc = WindowConfig.from_dict({"drift": 20})
+        assert wc.drift == 20
+        assert wc.anomaly is None
+        assert wc.correlation is None
+
+    def test_from_dict_empty(self):
+        wc = WindowConfig.from_dict({})
+        assert wc.drift is None
+        assert wc.anomaly is None
+        assert wc.correlation is None