margin 0.8.1__tar.gz → 0.9.0__tar.gz

{margin-0.8.1/margin.egg-info → margin-0.9.0}/PKG-INFO

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

@@ -29,7 +29,10 @@ from .ledger import Record, Ledger
 
 # Observability
 from .bridge import observe, observe_many, delta, to_uncertain
-from .calibrate import CalibrationResult, calibrate, calibrate_many, parser_from_calibration
+from .calibrate import (
+    CalibrationResult, calibrate, calibrate_many,
+    parser_from_calibration, recalibrate_parser, needs_recalibration,
+)
 from .composite import CompositeObservation, AggregateStrategy
 from .diff import ComponentChange, Diff, diff
 from .events import EventBus
@@ -95,7 +98,7 @@ from .causal import (
 )
 
 # Streaming
-from .streaming import DriftTracker, AnomalyTracker, CorrelationTracker, Monitor
+from .streaming import DriftTracker, AnomalyTracker, CorrelationTracker, Monitor, WindowConfig
 
 # Config
 from .config import from_config, load_config

{margin-0.8.1 → margin-0.9.0}/margin/calibrate.py

@@ -3,6 +3,9 @@ Threshold derivation from historical data.
 
 Takes a set of "known healthy" measurements and derives baselines and
 thresholds automatically.
+
+Also provides runtime recalibration: detect when a baseline has drifted
+and construct a replacement Parser with updated baselines/thresholds.
 """
 
 from __future__ import annotations
@@ -151,6 +154,138 @@ def calibrate_many(
     return baselines, thresholds
 
 
+def needs_recalibration(
+    calibration_samples: list[float],
+    recent_samples: list[float],
+    mean_shift_threshold: float = 0.2,
+    std_ratio_high: float = 2.0,
+    std_ratio_low: float = 0.5,
+    min_recent: int = 5,
+) -> bool:
+    """
+    Return True if recent values suggest the baseline has drifted.
+
+    Uses distribution comparison between calibration-time healthy data and
+    a recent window to detect two signals:
+
+      Signal A — mean shift: the operating centre has moved by more than
+        `mean_shift_threshold` (relative fraction, default 20%).
+
+      Signal B — spread change: variance has doubled (`std_ratio > 2.0`)
+        or halved (`std_ratio < 0.5`) relative to the calibration period.
+
+    Returns True when either signal fires and there are enough recent samples.
+    A third signal (AnomalyState.ANOMALOUS at healthy sigma) must be checked
+    externally via AnomalyTracker — see `needs_recalibration` docs.
+
+    Args:
+        calibration_samples:  original healthy measurements used to build the Parser
+        recent_samples:       recent window of observed values
+        mean_shift_threshold: relative mean shift that triggers recalibration (default 0.2)
+        std_ratio_high:       std ratio above which spread is considered changed (default 2.0)
+        std_ratio_low:        std ratio below which spread is considered changed (default 0.5)
+        min_recent:           minimum recent samples required to make a judgment (default 5)
+    """
+    if len(recent_samples) < min_recent or len(calibration_samples) < 2:
+        return False
+
+    from .anomaly import check_distribution
+    ds = check_distribution(recent_samples, calibration_samples)
+
+    mean_shifted = abs(ds.mean_shift) > mean_shift_threshold
+    spread_changed = ds.std_ratio > std_ratio_high or ds.std_ratio < std_ratio_low
+
+    return mean_shifted or spread_changed
+
+
+def recalibrate_parser(
+    parser: Parser,
+    new_healthy_data: dict[str, list[float]],
+    polarities: Optional[dict[str, bool]] = None,
+    components: Optional[list[str]] = None,
+    intact_fraction: float = 0.70,
+    ablated_fraction: float = 0.30,
+    active_min: float = 0.05,
+) -> tuple[Parser, dict[str, CalibrationResult]]:
+    """
+    Return a new Parser with updated baselines for components whose healthy
+    operating range has drifted.
+
+    Does NOT mutate the input parser — returns a replacement. Components not
+    in `new_healthy_data` (or not in `components`) keep their existing
+    baselines and thresholds unchanged.
+
+    Use after `needs_recalibration()` signals that a component's baseline
+    is stale, or when you have a new labeled window of known-healthy data.
+
+    Args:
+        parser:           the existing Parser to replace
+        new_healthy_data: {component: [new_healthy_measurements]}
+        polarities:       {component: higher_is_better} overrides (defaults
+                          to existing parser polarity for each component)
+        components:       allowlist of components to recalibrate; if None,
+                          all components in new_healthy_data are recalibrated
+        intact_fraction:  fraction of baseline for intact threshold
+        ablated_fraction: fraction of baseline for ablated threshold
+        active_min:       minimum correction magnitude
+
+    Returns:
+        (new_parser, results) where results is {component: CalibrationResult}
+        for each recalibrated component.
+
+    Transition notes:
+    - Historical Ledger Observations remain anchored to the baseline that was
+      active when they were recorded. Recalibration does not rewrite history.
+    - After recalibrating, rebuild Monitor from the new Parser:
+        save_monitor(old_monitor, "checkpoint.json")  # optional audit trail
+        new_monitor = Monitor(new_parser, drift_window=..., anomaly_window=...,
+                               correlation_window=...)
+    - Per-tracker windows should match the old Monitor's windows for continuity.
+    """
+    polarities = polarities or {}
+    to_recalibrate = set(components) if components else set(new_healthy_data.keys())
+
+    results: dict[str, CalibrationResult] = {}
+    new_baselines: dict[str, float] = {}
+    new_component_thresholds: dict[str, Thresholds] = {}
+
+    for name in to_recalibrate:
+        if name not in new_healthy_data:
+            continue
+        vals = new_healthy_data[name]
+        # 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)
+        result = calibrate(vals, hib, intact_fraction, ablated_fraction, active_min)
+        results[name] = result
+        new_baselines[name] = result.baseline
+        new_component_thresholds[name] = result.thresholds
+
+    # Merge: new overrides old; unrecalibrated components are preserved verbatim
+    merged_baselines = {**parser.baselines, **new_baselines}
+    merged_component_thresholds = {**parser.component_thresholds, **new_component_thresholds}
+
+    # Default thresholds: recalibrate if the first component was recalibrated,
+    # otherwise keep the existing default.
+    first_name = list(parser.baselines.keys())[0] if parser.baselines else None
+    if first_name and first_name in new_component_thresholds:
+        default_thresholds = new_component_thresholds.pop(first_name)
+        merged_component_thresholds.pop(first_name, None)
+    else:
+        default_thresholds = parser.thresholds
+        # Remove first component from component_thresholds if it was there
+        if first_name:
+            merged_component_thresholds.pop(first_name, None)
+
+    new_parser = Parser(
+        baselines=merged_baselines,
+        thresholds=default_thresholds,
+        component_thresholds=merged_component_thresholds,
+    )
+
+    return new_parser, results
+
+
 def parser_from_calibration(
     component_values: dict[str, list[float]],
     polarities: Optional[dict[str, bool]] = None,

{margin-0.8.1 → margin-0.9.0}/margin/causal.py

@@ -45,6 +45,10 @@ class CausalLink:
     strength:   0.0-1.0, how strong the relationship is (1.0 = deterministic)
     condition:  optional — this link only applies when source is in this health state
     evidence:   free text — why we believe this link exists
+    origin:     "asserted" (manually declared) or "discovered" (auto_causal_graph).
+                Asserted links are authoritative. Discovered links are correlational
+                heuristics — lag-based causal direction is plausible but not proven.
+                Never treat discovered links as ground truth in high-stakes domains.
     """
     source: str
     target: str
@@ -52,6 +56,15 @@ class CausalLink:
     strength: float = 1.0
     condition: Optional[Health] = None
     evidence: str = ""
+    origin: str = "asserted"   # "asserted" | "discovered"
+
+    @property
+    def is_asserted(self) -> bool:
+        return self.origin == "asserted"
+
+    @property
+    def is_discovered(self) -> bool:
+        return self.origin == "discovered"
 
     def to_dict(self) -> dict:
         d = {
@@ -59,6 +72,7 @@ class CausalLink:
             "cause_type": self.cause_type.value,
             "strength": round(self.strength, 4),
             "evidence": self.evidence,
+            "origin": self.origin,
         }
         if self.condition:
             d["condition"] = self.condition.value
@@ -72,11 +86,13 @@ class CausalLink:
             strength=d.get("strength", 1.0),
             condition=Health(d["condition"]) if "condition" in d else None,
             evidence=d.get("evidence", ""),
+            origin=d.get("origin", "asserted"),
         )
 
     def __repr__(self) -> str:
         cond = f" when {self.condition.value}" if self.condition else ""
-        return f"{self.source} --{self.cause_type.value}--> {self.target}{cond}"
+        tag = "[discovered]" if self.is_discovered else ""
+        return f"{self.source} --{self.cause_type.value}--> {self.target}{cond}{tag}"
 
 
 # -----------------------------------------------------------------------
@@ -124,6 +140,14 @@ class CausalGraph:
         """All links where `component` is the source (what it affects)."""
         return [l for l in self.links if l.source == component]
 
+    def asserted_links(self) -> list[CausalLink]:
+        """Links that were manually declared (authoritative)."""
+        return [l for l in self.links if l.is_asserted]
+
+    def discovered_links(self) -> list[CausalLink]:
+        """Links auto-discovered via correlation (heuristic, not proven)."""
+        return [l for l in self.links if l.is_discovered]
+
     def upstream(self, component: str, depth: int = 10) -> list[str]:
         """All components upstream of `component` (transitive causes)."""
         visited = set()

{margin-0.8.1 → margin-0.9.0}/margin/correlate.py

@@ -85,6 +85,7 @@ class Correlation:
             cause_type=cause_type,
             strength=self.strength,
             evidence=f"auto-correlated: r={self.coefficient:.3f}, lag={self.lag}, n={self.n_samples}",
+            origin="discovered",  # lag-based causal direction is a heuristic, not proven
         )
 
     def to_dict(self) -> dict:

{margin-0.8.1 → margin-0.9.0}/margin/ledger.py

@@ -109,12 +109,20 @@ class Ledger:
     """
     Accumulates Records across a session.
     Provides aggregate stats and renders the intervention history.
+
+    max_records: optional bound on records kept. When set, old records
+                 are dropped (oldest first) on each append. Use this for
+                 long-running production loops to prevent unbounded growth.
+                 None (default) = unbounded, suitable for batch/replay use.
     """
     label: str = ""
     records: list[Record] = field(default_factory=list)
+    max_records: Optional[int] = None
 
     def append(self, record: Record) -> None:
         self.records.append(record)
+        if self.max_records is not None and len(self.records) > self.max_records:
+            self.records.pop(0)
 
     def __len__(self) -> int:
         return len(self.records)

{margin-0.8.1 → margin-0.9.0}/margin/observation.py

@@ -10,6 +10,7 @@ Expression:   composed snapshot — all observations + corrections at one moment
 from __future__ import annotations
 
 import json
+import warnings
 from dataclasses import dataclass, field
 from datetime import datetime
 from enum import Enum
@@ -161,8 +162,8 @@ class Correction:
         return {
             "target": self.target,
             "op": self.op.value,
-            "alpha": round(self.alpha, 4),
-            "magnitude": round(self.magnitude, 4),
+            "alpha": self.alpha,
+            "magnitude": self.magnitude,
             "triggered_by": self.triggered_by,
             "provenance": self.provenance,
         }
@@ -198,6 +199,18 @@ class Expression:
     label: str = ""
     step: Optional[int] = None
 
+    def __post_init__(self) -> None:
+        if self.observations:
+            weakest = min(o.confidence for o in self.observations)
+            if self.confidence > weakest:
+                warnings.warn(
+                    f"Expression.confidence ({self.confidence.value}) exceeds the weakest "
+                    f"observation confidence ({weakest.value}). This overclaims certainty "
+                    "and will cause min_confidence policy gates to fire incorrectly. "
+                    "Use Parser.parse() to construct Expressions with correct net confidence.",
+                    stacklevel=2,
+                )
+
     def health_of(self, name: str) -> Optional[Health]:
         for o in self.observations:
             if o.name == name:

{margin-0.8.1 → margin-0.9.0}/margin/persist.py

@@ -25,6 +25,9 @@ def save_monitor(monitor: Monitor, path: str) -> None:
     state = {
         "step": monitor.step,
         "window": monitor.window,
+        "drift_window": monitor.drift_window,
+        "anomaly_window": monitor.anomaly_window,
+        "correlation_window": monitor.correlation_window,
         "drift": {},
         "anomaly": {},
         "correlation": {
@@ -59,7 +62,16 @@ def load_monitor(path: str, parser: Parser, **kwargs) -> Monitor:
     data = json.loads(Path(path).read_text())
 
     window = data.get("window", kwargs.pop("window", 100))
-    monitor = Monitor(parser, window=window, **kwargs)
+    drift_window = data.get("drift_window", kwargs.pop("drift_window", None))
+    anomaly_window = data.get("anomaly_window", kwargs.pop("anomaly_window", None))
+    correlation_window = data.get("correlation_window", kwargs.pop("correlation_window", None))
+    monitor = Monitor(
+        parser, window=window,
+        drift_window=drift_window,
+        anomaly_window=anomaly_window,
+        correlation_window=correlation_window,
+        **kwargs,
+    )
     monitor._step = data.get("step", 0)
 
     # Restore drift tracker observations
@@ -97,24 +109,36 @@ def replay(
     data: list[dict[str, float]],
     timestamps: Optional[list[datetime]] = None,
     window: int = 100,
+    drift_window: Optional[int] = None,
+    anomaly_window: Optional[int] = None,
+    correlation_window: Optional[int] = None,
     **kwargs,
 ) -> tuple[Monitor, list[dict]]:
     """
     Replay historical data through a Monitor.
 
     Args:
-        parser:     Parser for health classification
-        data:       list of {component: value} dicts, one per step
-        timestamps: optional timestamps per step (defaults to 1-second intervals)
-        window:     tracker window size
-        **kwargs:   passed to Monitor
+        parser:            Parser for health classification
+        data:              list of {component: value} dicts, one per step
+        timestamps:        optional timestamps per step (defaults to 1-second intervals)
+        window:            base tracker window size (all trackers inherit if per-tracker not set)
+        drift_window:      override window for DriftTracker
+        anomaly_window:    override window for AnomalyTracker
+        correlation_window: override window for CorrelationTracker
+        **kwargs:          passed to Monitor
 
     Returns (monitor, snapshots) where snapshots is a list of status dicts,
     one per step.
     """
     from datetime import timedelta
 
-    monitor = Monitor(parser, window=window, **kwargs)
+    monitor = Monitor(
+        parser, window=window,
+        drift_window=drift_window,
+        anomaly_window=anomaly_window,
+        correlation_window=correlation_window,
+        **kwargs,
+    )
     snapshots = []
 
     t0 = timestamps[0] if timestamps else datetime(2000, 1, 1)
@@ -132,6 +156,9 @@ def replay_csv(
     path: str,
     timestamp_column: Optional[str] = None,
     window: int = 100,
+    drift_window: Optional[int] = None,
+    anomaly_window: Optional[int] = None,
+    correlation_window: Optional[int] = None,
     **kwargs,
 ) -> tuple[Monitor, list[dict]]:
     """
@@ -166,4 +193,10 @@ def replay_csv(
             if values:
                 rows.append(values)
 
-    return replay(parser, rows, timestamps or None, window, **kwargs)
+    return replay(
+        parser, rows, timestamps or None, window,
+        drift_window=drift_window,
+        anomaly_window=anomaly_window,
+        correlation_window=correlation_window,
+        **kwargs,
+    )

{margin-0.8.1 → margin-0.9.0}/margin/streaming.py

@@ -16,6 +16,23 @@ from dataclasses import dataclass, field
 from datetime import datetime
 from typing import Optional
 
+
+@dataclass
+class WindowConfig:
+    """
+    Per-concern window sizes for Monitor.
+
+    drift:        window for DriftTracker (how many steps to classify trajectory)
+    anomaly:      window for AnomalyTracker (reference window for outlier detection)
+    correlation:  window for CorrelationTracker (how many steps for pairwise correlation)
+
+    All default to None, meaning "inherit the Monitor's base `window` parameter."
+    Rule of thumb: anomaly ≈ 4× drift, correlation ≈ 10× drift.
+    """
+    drift: Optional[int] = None
+    anomaly: Optional[int] = None
+    correlation: Optional[int] = None
+
 from .confidence import Confidence
 from .health import Health, Thresholds, classify
 from .observation import Observation, Expression
@@ -340,11 +357,22 @@ class Monitor:
         self,
         parser,
         window: int = 100,
+        drift_window: Optional[int] = None,
+        anomaly_window: Optional[int] = None,
+        correlation_window: Optional[int] = None,
+        window_config: Optional[WindowConfig] = None,
         min_correlation: float = 0.7,
         anomaly_min_reference: int = 10,
     ):
         self.parser = parser
         self.window = window
+
+        # Resolve per-tracker windows: window_config > named params > base window
+        cfg = window_config or WindowConfig()
+        self.drift_window = cfg.drift or drift_window or window
+        self.anomaly_window = cfg.anomaly or anomaly_window or window
+        self.correlation_window = cfg.correlation or correlation_window or window
+
         self._expression: Optional[Expression] = None
         self._step = 0
 
@@ -352,17 +380,16 @@ class Monitor:
         self._drift_trackers: dict[str, DriftTracker] = {}
         self._anomaly_trackers: dict[str, AnomalyTracker] = {}
 
-        for name, baseline in parser.baselines.items():
-            thresholds = parser._thresholds_for(name)
-            self._drift_trackers[name] = DriftTracker(name, window=window)
+        for name in parser.baselines:
+            self._drift_trackers[name] = DriftTracker(name, window=self.drift_window)
             self._anomaly_trackers[name] = AnomalyTracker(
-                name, window=window, min_reference=anomaly_min_reference,
+                name, window=self.anomaly_window, min_reference=anomaly_min_reference,
             )
 
         # Correlation tracker across all components
         self._correlation_tracker = CorrelationTracker(
             list(parser.baselines.keys()),
-            window=window,
+            window=self.correlation_window,
             min_correlation=min_correlation,
         )
 
@@ -455,4 +482,9 @@ class Monitor:
         self._correlation_tracker.reset()
 
     def __repr__(self) -> str:
-        return f"Monitor(step={self._step}, {len(self._drift_trackers)} components)"
+        windows_uniform = (self.drift_window == self.anomaly_window == self.correlation_window)
+        if windows_uniform:
+            w = f"window={self.drift_window}"
+        else:
+            w = f"drift={self.drift_window}, anomaly={self.anomaly_window}, corr={self.correlation_window}"
+        return f"Monitor(step={self._step}, {len(self._drift_trackers)} components, {w})"

{margin-0.8.1 → margin-0.9.0/margin.egg-info}/PKG-INFO

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "margin"
-version = "0.8.1"
+version = "0.9.0"
 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"}