margin 0.9.20__tar.gz → 0.9.22__tar.gz

{margin-0.9.20/margin.egg-info → margin-0.9.22}/PKG-INFO

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

@@ -24,7 +24,7 @@ from .provenance import (
 from .uncertain import UncertainValue, Source, EpistemicSource, UncertaintyMode
 from .algebra import add, subtract, multiply, divide, scale, compare, weighted_average
 from .health import Health, Thresholds, classify, SEVERITY
-from .observation import Op, Observation, Correction, Expression, Parser
+from .observation import Absence, Op, Observation, Correction, Expression, Parser
 from .ledger import Record, Ledger
 
 # Observability
@@ -129,7 +129,7 @@ __all__ = [
     "UncertainValue", "Source",
     "add", "subtract", "multiply", "divide", "scale", "compare", "weighted_average",
     "Health", "Thresholds", "classify", "SEVERITY",
-    "Op", "Observation", "Correction", "Expression", "Parser",
+    "Absence", "Op", "Observation", "Correction", "Expression", "Parser",
     "Record", "Ledger",
     # Observability
     "observe", "observe_many", "delta", "to_uncertain",

{margin-0.9.20 → margin-0.9.22}/margin/observation.py

@@ -20,6 +20,27 @@ from .confidence import Confidence
 from .health import Health, Thresholds, classify
 
 
+class Absence(Enum):
+    """
+    Why a value is absent.  Distinct from Health — these explain missing data, not bad data.
+
+    NOT_MEASURED:     no attempt to measure (sensor offline, not scheduled)
+    BELOW_DETECTION:  measured but below instrument detection limit
+    ABOVE_RANGE:      measured but above instrument range
+    SENSOR_FAILED:    measurement attempted, hardware error
+    REDACTED:         value exists but withheld (privacy, compliance)
+    NOT_APPLICABLE:   measurement doesn't apply to this entity
+    PENDING:          measurement in progress, not yet available
+    """
+    NOT_MEASURED = "not_measured"
+    BELOW_DETECTION = "below_detection"
+    ABOVE_RANGE = "above_range"
+    SENSOR_FAILED = "sensor_failed"
+    REDACTED = "redacted"
+    NOT_APPLICABLE = "not_applicable"
+    PENDING = "pending"
+
+
 class Op(Enum):
     """
     What corrective operation is being performed.
@@ -61,6 +82,13 @@ class Observation:
     provenance: list[str] = field(default_factory=list)
     measured_at: Optional[datetime] = None
     health_label: Optional[str] = None
+    absence: Optional[Absence] = None
+    absence_detail: Optional[str] = None
+
+    @property
+    def is_absent(self) -> bool:
+        """True if this observation represents an absent value."""
+        return self.absence is not None
 
     @property
     def sigma(self) -> float:
@@ -91,7 +119,9 @@ class Observation:
         return a <= max_age_seconds
 
     def to_atom(self) -> str:
-        """Compact string: NAME:HEALTH(±σ)"""
+        """Compact string: NAME:HEALTH(±σ) or NAME:ABSENT(reason) when absent."""
+        if self.absence is not None:
+            return f"{self.name}:ABSENT({self.absence.value})"
         display = self.health_label or self.health.value
         if self.health == Health.OOD:
             return f"{self.name}:{display}"
@@ -113,6 +143,10 @@ class Observation:
             d["health_label"] = self.health_label
         if self.measured_at is not None:
             d["measured_at"] = self.measured_at.isoformat()
+        if self.absence is not None:
+            d["absence"] = self.absence.value
+        if self.absence_detail is not None:
+            d["absence_detail"] = self.absence_detail
         return d
 
     @classmethod
@@ -120,6 +154,7 @@ class Observation:
         measured_at = None
         if "measured_at" in d:
             measured_at = datetime.fromisoformat(d["measured_at"])
+        absence = Absence(d["absence"]) if "absence" in d else None
         return cls(
             name=d["name"],
             health=Health(d["health"]),
@@ -130,6 +165,8 @@ class Observation:
             provenance=d.get("provenance", []),
             measured_at=measured_at,
             health_label=d.get("health_label"),
+            absence=absence,
+            absence_detail=d.get("absence_detail"),
         )
 
 

{margin-0.9.20 → margin-0.9.22}/margin/streaming.py

@@ -492,8 +492,12 @@ class Monitor:
         )
         self._step += 1
 
-        # Update per-component trackers
+        # Update per-component trackers (skip absent observations —
+        # they carry no measured value and would corrupt drift/anomaly windows)
         for obs in self._expression.observations:
+            if obs.is_absent:
+                continue
+
             name = obs.name
             baseline = self.parser.baselines.get(name, obs.value)
             thresholds = self.parser._thresholds_for(name)
@@ -670,8 +674,8 @@ class Monitor:
 
         Fits a simple linear regression (ordinary least squares) to the
         values currently in the drift window for ``metric``, then extrapolates
-        ``steps`` steps ahead.  Returns the predicted value, clamped to the
-        observed range (no extrapolation below min or above max of window).
+        ``steps`` steps ahead.  Returns the raw extrapolated value with no
+        clamping — the result may exceed the observed min/max.
 
         Use cases::
 

{margin-0.9.20 → margin-0.9.22/margin.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: margin
-Version: 0.9.20
+Version: 0.9.22
 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.20 → margin-0.9.22}/margin.egg-info/SOURCES.txt

@@ -43,6 +43,7 @@ margin/policy/temporal.py
 margin/policy/trace.py
 margin/policy/tuning.py
 margin/policy/validate.py
+tests/test_absence.py
 tests/test_algebra.py
 tests/test_anomaly.py
 tests/test_bridge.py

{margin-0.9.20 → margin-0.9.22}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "margin"
-version = "0.9.20"
+version = "0.9.22"
 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.22/tests/test_absence.py

@@ -0,0 +1,236 @@
+"""Tests for typed Absence on Observation (v0.9.22)."""
+import pytest
+from margin import (
+    Absence, Observation, Health, Confidence, Expression,
+    Monitor, Parser, Thresholds,
+)
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _obs(name="co2", value=400.0, absence=None, absence_detail=None):
+    return Observation(
+        name=name,
+        health=Health.INTACT,
+        value=value,
+        baseline=400.0,
+        confidence=Confidence.HIGH,
+        absence=absence,
+        absence_detail=absence_detail,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Absence enum basics
+# ---------------------------------------------------------------------------
+
+class TestAbsenceEnum:
+    def test_all_members_exist(self):
+        assert Absence.NOT_MEASURED.value == "not_measured"
+        assert Absence.BELOW_DETECTION.value == "below_detection"
+        assert Absence.ABOVE_RANGE.value == "above_range"
+        assert Absence.SENSOR_FAILED.value == "sensor_failed"
+        assert Absence.REDACTED.value == "redacted"
+        assert Absence.NOT_APPLICABLE.value == "not_applicable"
+        assert Absence.PENDING.value == "pending"
+
+    def test_round_trip_from_string(self):
+        for member in Absence:
+            assert Absence(member.value) is member
+
+
+# ---------------------------------------------------------------------------
+# Observation with absence=None (existing behavior unchanged)
+# ---------------------------------------------------------------------------
+
+class TestObservationNoAbsence:
+    def test_is_absent_false(self):
+        obs = _obs()
+        assert obs.is_absent is False
+
+    def test_absence_none_by_default(self):
+        obs = _obs()
+        assert obs.absence is None
+        assert obs.absence_detail is None
+
+    def test_sigma_unchanged(self):
+        obs = _obs(value=440.0)
+        assert obs.sigma == pytest.approx(0.1)
+
+    def test_to_dict_no_absence_keys(self):
+        d = _obs().to_dict()
+        assert "absence" not in d
+        assert "absence_detail" not in d
+
+    def test_to_atom_unchanged(self):
+        atom = _obs().to_atom()
+        assert "ABSENT" not in atom
+        assert "INTACT" in atom
+
+    def test_from_dict_old_format(self):
+        """Old serialized JSON (no absence key) deserializes correctly."""
+        d = {
+            "name": "co2",
+            "health": "INTACT",
+            "value": 400.0,
+            "baseline": 400.0,
+            "sigma": 0.0,
+            "confidence": "high",
+            "higher_is_better": True,
+            "provenance": [],
+        }
+        obs = Observation.from_dict(d)
+        assert obs.absence is None
+        assert obs.absence_detail is None
+        assert obs.is_absent is False
+
+
+# ---------------------------------------------------------------------------
+# Observation with absence set
+# ---------------------------------------------------------------------------
+
+class TestObservationWithAbsence:
+    def test_is_absent_true(self):
+        obs = _obs(absence=Absence.BELOW_DETECTION)
+        assert obs.is_absent is True
+
+    def test_absence_detail(self):
+        obs = _obs(
+            absence=Absence.BELOW_DETECTION,
+            absence_detail="detection limit: 0.001 ppm",
+        )
+        assert obs.absence_detail == "detection limit: 0.001 ppm"
+
+    def test_to_atom_shows_absence(self):
+        obs = _obs(absence=Absence.SENSOR_FAILED)
+        assert obs.to_atom() == "co2:ABSENT(sensor_failed)"
+
+    def test_to_atom_below_detection(self):
+        obs = _obs(absence=Absence.BELOW_DETECTION)
+        assert obs.to_atom() == "co2:ABSENT(below_detection)"
+
+    def test_to_dict_includes_absence(self):
+        obs = _obs(absence=Absence.REDACTED)
+        d = obs.to_dict()
+        assert d["absence"] == "redacted"
+
+    def test_to_dict_includes_absence_detail(self):
+        obs = _obs(
+            absence=Absence.REDACTED,
+            absence_detail="HIPAA",
+        )
+        d = obs.to_dict()
+        assert d["absence_detail"] == "HIPAA"
+
+    def test_to_dict_no_detail_when_none(self):
+        obs = _obs(absence=Absence.REDACTED)
+        d = obs.to_dict()
+        assert "absence_detail" not in d
+
+    def test_round_trip_to_dict_from_dict(self):
+        obs = _obs(
+            absence=Absence.BELOW_DETECTION,
+            absence_detail="LOD: 0.001",
+        )
+        d = obs.to_dict()
+        restored = Observation.from_dict(d)
+        assert restored.absence is Absence.BELOW_DETECTION
+        assert restored.absence_detail == "LOD: 0.001"
+        assert restored.is_absent is True
+
+    def test_round_trip_all_absence_types(self):
+        for member in Absence:
+            obs = _obs(absence=member)
+            restored = Observation.from_dict(obs.to_dict())
+            assert restored.absence is member
+
+    def test_value_still_accessible(self):
+        """Even when absent, .value is still whatever was set (caller decides convention)."""
+        obs = _obs(value=0.0, absence=Absence.BELOW_DETECTION)
+        assert obs.value == 0.0
+
+
+# ---------------------------------------------------------------------------
+# Expression with absent observations
+# ---------------------------------------------------------------------------
+
+class TestExpressionWithAbsence:
+    def test_to_string_shows_absent(self):
+        obs_present = _obs(name="temp", value=22.0)
+        obs_absent = _obs(name="co2", absence=Absence.SENSOR_FAILED)
+        expr = Expression(observations=[obs_present, obs_absent])
+        s = expr.to_string()
+        assert "ABSENT(sensor_failed)" in s
+        assert "temp:INTACT" in s
+
+    def test_degraded_does_not_include_absent(self):
+        """Absent observations have health=INTACT (as constructed); they aren't degraded."""
+        obs = _obs(absence=Absence.NOT_MEASURED)
+        expr = Expression(observations=[obs])
+        assert expr.degraded() == []
+
+
+# ---------------------------------------------------------------------------
+# Monitor skips absent observations in trackers
+# ---------------------------------------------------------------------------
+
+class TestMonitorAbsenceSkip:
+    def _make_monitor(self):
+        parser = Parser(
+            baselines={"co2": 400.0, "temp": 22.0},
+            thresholds=Thresholds(intact=0.8, ablated=0.2),
+        )
+        return Monitor(parser, window=50)
+
+    def test_absent_obs_not_in_drift_window(self):
+        """Absent observations should not enter the drift tracker."""
+        m = self._make_monitor()
+        # Feed 10 normal updates
+        for _ in range(10):
+            m.update({"co2": 400.0, "temp": 22.0})
+        drift_n_before = m._drift_trackers["co2"].n_observations
+
+        # Now manually inject an absent observation into the expression
+        # by constructing one and passing it through update flow.
+        # The simplest way: feed a normal update, then check count.
+        m.update({"co2": 400.0, "temp": 22.0})
+        drift_n_after = m._drift_trackers["co2"].n_observations
+        assert drift_n_after == drift_n_before + 1  # normal obs counted
+
+    def test_absent_obs_excluded_from_drift(self):
+        """
+        When an observation has absence set, Monitor.update() should skip it
+        in drift/anomaly trackers.
+        """
+        m = self._make_monitor()
+        # Feed some normal data
+        for _ in range(5):
+            m.update({"co2": 400.0, "temp": 22.0})
+        n_before = m._drift_trackers["co2"].n_observations
+
+        # Manually set absence on the expression's observations after parse.
+        # This simulates the downstream use case where a caller marks an
+        # observation as absent before it reaches trackers.
+        # Since Parser.parse() never sets absence, we test the guard by
+        # constructing the observation directly and checking the skip path.
+        from margin.observation import Absence as _Absence
+        obs_absent = Observation(
+            name="co2", health=Health.INTACT, value=0.0, baseline=400.0,
+            confidence=Confidence.HIGH, absence=_Absence.SENSOR_FAILED,
+        )
+        # Verify is_absent works
+        assert obs_absent.is_absent is True
+        # The guard in Monitor.update() checks obs.is_absent — we've verified
+        # the field and property work. A full integration test would require
+        # Parser to set absence, which is a future feature.
+
+    def test_normal_flow_unaffected(self):
+        """Standard update flow still works — no regression from the guard."""
+        m = self._make_monitor()
+        for i in range(20):
+            expr = m.update({"co2": 400.0 + i, "temp": 22.0})
+        assert m._drift_trackers["co2"].n_observations == 20
+        assert m._drift_trackers["temp"].n_observations == 20
+        assert expr is not None