margin 0.9.9__tar.gz → 0.9.10__tar.gz

{margin-0.9.9/margin.egg-info → margin-0.9.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: margin
-Version: 0.9.9
+Version: 0.9.10
 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.9 → margin-0.9.10}/margin/events.py

@@ -1,8 +1,22 @@
 """
 Event bus for validity invalidation.
 
-Wires Validity.until_event() to actual event dispatch. When an event
-fires, all values whose Validity references that event become stale.
+Standalone utility — not wired into Monitor or the evaluation loop.
+Use directly in event-driven systems where values should become stale
+when something changes (config reload, model update, deployment).
+
+    bus = EventBus()
+    bus.fire("config_reload")
+
+    v = Validity.until_event("config_reload")
+    bus.is_valid(v)  # False — invalidated
+
+    bus.on("deploy", lambda evt, ts: print(f"deployed at {ts}"))
+
+When an event fires, all Validity descriptors that reference it via
+Validity.until_event() become stale. bus.is_valid() / bus.is_value_valid()
+check this. EventBus does NOT integrate with Monitor health transitions;
+for that use case, attach a listener to Monitor.update() manually.
 """
 
 from __future__ import annotations

{margin-0.9.9 → margin-0.9.10}/margin/persist.py

@@ -17,6 +17,7 @@ from pathlib import Path
 from typing import Optional
 
 from .observation import Observation, Expression, Parser
+from .provenance import ProvenanceGraph
 from .streaming import Monitor, DriftTracker, AnomalyTracker, CorrelationTracker
 
 
@@ -41,6 +42,8 @@ def save_monitor(monitor: Monitor, path: str) -> None:
             "series": {c: list(d) for c, d in monitor._correlation_tracker._series.items()},
             "n_updates": monitor._correlation_tracker.n_updates,
         } if monitor._correlation_tracker is not None else None,
+        "provenance_graph": monitor.provenance_graph.to_dict()
+            if monitor.provenance_graph is not None else None,
     }
 
     for name, dt in monitor._drift_trackers.items():
@@ -85,6 +88,11 @@ def load_monitor(path: str, parser: Parser, **kwargs) -> Monitor:
     )
     monitor._step = data.get("step", 0)
 
+    # Restore provenance graph if present
+    pg_data = data.get("provenance_graph")
+    if pg_data is not None:
+        monitor.provenance_graph = ProvenanceGraph.from_dict(pg_data)
+
     # Restore drift tracker observations
     for name, dt_data in data.get("drift", {}).items():
         if name in monitor._drift_trackers:

{margin-0.9.9 → margin-0.9.10}/margin/streaming.py

@@ -63,6 +63,7 @@ class WindowConfig:
 from .confidence import Confidence
 from .health import Health, Thresholds, classify
 from .observation import Observation, Expression
+from .provenance import ProvenanceGraph
 from .drift import (
     DriftState, DriftDirection, DriftClassification,
     classify_drift,
@@ -391,6 +392,7 @@ class Monitor:
         min_correlation: float = 0.7,
         anomaly_min_reference: int = 10,
         features: Optional[set] = None,
+        provenance_graph: Optional[ProvenanceGraph] = None,
     ):
         """
         Args:
@@ -406,6 +408,11 @@ class Monitor:
                                   ``"anomaly"``, ``"correlation"}``; ``None`` (default)
                                   enables all three; ``set()`` disables all.
                                   ``"health"`` is always implied and need not be listed.
+            provenance_graph:     optional ProvenanceGraph; when provided, each
+                                  ``update()`` call records a root node
+                                  (``"monitor:step:N"``) and threads its ID into
+                                  every observation's ``provenance`` list, enabling
+                                  full lineage queries via ``monitor.provenance_graph``
         """
         self.parser = parser
         self.window = window
@@ -428,6 +435,7 @@ class Monitor:
                 stacklevel=2,
             )
 
+        self.provenance_graph: Optional[ProvenanceGraph] = provenance_graph
         self._expression: Optional[Expression] = None
         self._step = 0
 
@@ -469,6 +477,13 @@ class Monitor:
         """
         now = now or datetime.now()
 
+        # Record a step root in the provenance graph if one is attached.
+        # The step ID is prepended to any caller-supplied provenance tags so
+        # every observation carries both the step origin and the user context.
+        if self.provenance_graph is not None:
+            step_id = self.provenance_graph.create_root(f"monitor:step:{self._step}")
+            provenance = [step_id] + list(provenance or [])
+
         # Health classification via Parser
         self._expression = self.parser.parse(
             values, label=label, step=self._step,
@@ -546,6 +561,8 @@ class Monitor:
                     d["anomaly"][name] = tracker.classification.to_dict()
         if self._correlation_tracker is not None and self._correlation_tracker.matrix:
             d["correlations"] = self._correlation_tracker.matrix.to_dict()
+        if self.provenance_graph is not None:
+            d["provenance_nodes"] = len(self.provenance_graph.nodes)
         return d
 
     def reset_anomaly_reference(self, components: Optional[list[str]] = None) -> None:
@@ -586,4 +603,5 @@ class Monitor:
             feat = ""
         else:
             feat = f", features={{{', '.join(sorted(self.features))}}}"
-        return f"Monitor(step={self._step}, {len(self._drift_trackers)} components, {w}{feat})"
+        pg = ", provenance=True" if self.provenance_graph is not None else ""
+        return f"Monitor(step={self._step}, {len(self._drift_trackers)} components, {w}{feat}{pg})"

{margin-0.9.9 → margin-0.9.10/margin.egg-info}/PKG-INFO

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "margin"
-version = "0.9.9"
+version = "0.9.10"
 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.9 → margin-0.9.10}/tests/test_persist.py

@@ -10,6 +10,7 @@ from margin import (
     save_monitor, load_monitor, replay, replay_csv,
     DriftState, AnomalyState,
 )
+from margin.provenance import ProvenanceGraph
 
 
 def _parser():
@@ -264,3 +265,34 @@ class TestFeaturesRoundtrip:
 
         assert data["anomaly_min_reference"] == 25
         assert m2._anomaly_trackers["cpu"]._min_reference == 25
+
+
+class TestProvenanceGraphRoundtrip:
+    def test_provenance_graph_saved_and_restored(self):
+        p = _parser()
+        pg = ProvenanceGraph()
+        m = Monitor(p, provenance_graph=pg)
+        for i in range(3):
+            m.update({"cpu": 50.0, "mem": 70.0}, now=t0 + timedelta(seconds=i * 60))
+
+        with tempfile.NamedTemporaryFile(suffix=".json", delete=False) as f:
+            save_monitor(m, f.name)
+            m2 = load_monitor(f.name, p)
+            Path(f.name).unlink()
+
+        assert m2.provenance_graph is not None
+        assert len(m2.provenance_graph.nodes) == 3
+
+    def test_no_provenance_graph_not_saved(self):
+        p = _parser()
+        m = Monitor(p)
+        m.update({"cpu": 50.0, "mem": 70.0}, now=t0)
+
+        with tempfile.NamedTemporaryFile(suffix=".json", delete=False) as f:
+            save_monitor(m, f.name)
+            data = json.loads(Path(f.name).read_text())
+            m2 = load_monitor(f.name, p)
+            Path(f.name).unlink()
+
+        assert data.get("provenance_graph") is None
+        assert m2.provenance_graph is None

{margin-0.9.9 → margin-0.9.10}/tests/test_streaming.py

@@ -8,6 +8,7 @@ from margin import (
     DriftTracker, AnomalyTracker, CorrelationTracker, Monitor,
     WindowConfig,
 )
+from margin.provenance import ProvenanceGraph
 
 
 t0 = datetime(2026, 1, 1)
@@ -448,3 +449,73 @@ class TestWindowConfigSerialization:
         assert wc.drift is None
         assert wc.anomaly is None
         assert wc.correlation is None
+
+
+class TestMonitorProvenanceGraph:
+    def _parser(self):
+        return Parser({"cpu": 100.0}, Thresholds(intact=80.0, ablated=40.0))
+
+    def test_provenance_graph_off_by_default(self):
+        m = Monitor(self._parser())
+        assert m.provenance_graph is None
+
+    def test_provenance_graph_records_step_nodes(self):
+        pg = ProvenanceGraph()
+        m = Monitor(self._parser(), provenance_graph=pg)
+        m.update({"cpu": 90.0})
+        m.update({"cpu": 85.0})
+        assert len(pg.nodes) == 2
+
+    def test_observations_carry_step_provenance_id(self):
+        pg = ProvenanceGraph()
+        m = Monitor(self._parser(), provenance_graph=pg)
+        expr = m.update({"cpu": 90.0})
+        obs = expr.observations[0]
+        assert len(obs.provenance) == 1
+        assert obs.provenance[0] in pg.nodes
+
+    def test_user_provenance_tags_also_included(self):
+        pg = ProvenanceGraph()
+        m = Monitor(self._parser(), provenance_graph=pg)
+        expr = m.update({"cpu": 90.0}, provenance=["sensor-42"])
+        obs = expr.observations[0]
+        assert "sensor-42" in obs.provenance
+        # also has the step root ID
+        assert any(p in pg.nodes for p in obs.provenance)
+
+    def test_step_node_operation_name(self):
+        pg = ProvenanceGraph()
+        m = Monitor(self._parser(), provenance_graph=pg)
+        m.update({"cpu": 90.0})
+        node = next(iter(pg.nodes.values()))
+        assert node.operation == "monitor:step:0"
+
+    def test_status_includes_provenance_node_count(self):
+        pg = ProvenanceGraph()
+        m = Monitor(self._parser(), provenance_graph=pg)
+        m.update({"cpu": 90.0})
+        s = m.status()
+        assert s["provenance_nodes"] == 1
+
+    def test_status_no_provenance_key_when_none(self):
+        m = Monitor(self._parser())
+        m.update({"cpu": 90.0})
+        assert "provenance_nodes" not in m.status()
+
+    def test_repr_shows_provenance(self):
+        pg = ProvenanceGraph()
+        m = Monitor(self._parser(), provenance_graph=pg)
+        assert "provenance=True" in repr(m)
+
+    def test_repr_no_provenance_marker_when_none(self):
+        m = Monitor(self._parser())
+        assert "provenance" not in repr(m)
+
+    def test_trace_lineage_via_graph(self):
+        pg = ProvenanceGraph()
+        m = Monitor(self._parser(), provenance_graph=pg)
+        expr = m.update({"cpu": 90.0})
+        step_id = expr.observations[0].provenance[0]
+        lineage = pg.trace_lineage(step_id)
+        assert len(lineage) == 1
+        assert lineage[0].id == step_id