margin 0.1.0__py3-none-any.whl

margin/__init__.py

@@ -0,0 +1,114 @@
+"""
+Margin: typed uncertainty algebra and health classification.
+
+A framework for measurements that carry uncertainty, temporal validity,
+provenance, and typed health states — with an auditable correction ledger.
+
+Structure:
+    Foundation:    confidence, validity, provenance, uncertain, algebra,
+                   health, observation, ledger
+    Observability: bridge, calibrate, composite, diff, events, forecast,
+                   predicates, transitions
+    Policy:        policy/ (core, temporal, compose, tuning, trace, validate)
+    Contract:      contract
+    Causal:        causal
+"""
+
+# Foundation
+from .confidence import Confidence
+from .validity import Validity, ValidityMode
+from .provenance import new_id, are_correlated, merge
+from .uncertain import UncertainValue, Source
+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 .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 .composite import CompositeObservation, AggregateStrategy
+from .diff import ComponentChange, Diff, diff
+from .events import EventBus
+from .forecast import Forecast, forecast
+from .predicates import (
+    any_health, all_health, count_health, component_health,
+    any_degraded, confidence_below, sigma_below, any_correction,
+    all_of, any_of, not_, Rule, evaluate_rules,
+)
+from .transitions import Span, Transition, ComponentHistory, track, track_all
+
+# Policy
+from .policy import (
+    EscalationLevel, Escalation, Action, Constraint, PolicyRule, Policy,
+    health_sustained, health_for_at_least,
+    sigma_trending_below, fire_rate_above, no_improvement,
+    PolicyChain, CorrectionBundle, bundle_from_policy,
+    PolicyComparison, diff_policies, agreement_rate,
+    RuleStats, TuningResult,
+    analyze_backtest, suggest_tuning, apply_tuning,
+    RuleEvaluation, DecisionTrace,
+    trace_evaluate, trace_backtest,
+    ValidationIssue, ValidationResult, validate,
+)
+
+# Contract
+from .contract import (
+    TermStatus, TermResult, ContractTerm,
+    HealthTarget, ReachHealth, SustainHealth,
+    RecoveryThreshold, NoHarmful,
+    ContractResult, Contract,
+)
+
+# Causal
+from .causal import (
+    CauseType, CausalLink, CausalGraph,
+    CauseExplanation, Explanation,
+)
+
+# Loop
+from .loop import StepResult, step, run
+
+__all__ = [
+    # Foundation
+    "Confidence",
+    "Validity", "ValidityMode",
+    "new_id", "are_correlated", "merge",
+    "UncertainValue", "Source",
+    "add", "subtract", "multiply", "divide", "scale", "compare", "weighted_average",
+    "Health", "Thresholds", "classify", "SEVERITY",
+    "Op", "Observation", "Correction", "Expression", "Parser",
+    "Record", "Ledger",
+    # Observability
+    "observe", "observe_many", "delta", "to_uncertain",
+    "CalibrationResult", "calibrate", "calibrate_many", "parser_from_calibration",
+    "CompositeObservation", "AggregateStrategy",
+    "ComponentChange", "Diff", "diff",
+    "EventBus",
+    "Forecast", "forecast",
+    "any_health", "all_health", "count_health", "component_health",
+    "any_degraded", "confidence_below", "sigma_below", "any_correction",
+    "all_of", "any_of", "not_", "Rule", "evaluate_rules",
+    "Span", "Transition", "ComponentHistory", "track", "track_all",
+    # Policy
+    "EscalationLevel", "Escalation", "Action", "Constraint", "PolicyRule", "Policy",
+    "health_sustained", "health_for_at_least",
+    "sigma_trending_below", "fire_rate_above", "no_improvement",
+    "PolicyChain", "CorrectionBundle", "bundle_from_policy",
+    "PolicyComparison", "diff_policies", "agreement_rate",
+    "RuleStats", "TuningResult",
+    "analyze_backtest", "suggest_tuning", "apply_tuning",
+    "RuleEvaluation", "DecisionTrace",
+    "trace_evaluate", "trace_backtest",
+    "ValidationIssue", "ValidationResult", "validate",
+    # Contract
+    "TermStatus", "TermResult", "ContractTerm",
+    "HealthTarget", "ReachHealth", "SustainHealth",
+    "RecoveryThreshold", "NoHarmful",
+    "ContractResult", "Contract",
+    # Causal
+    "CauseType", "CausalLink", "CausalGraph",
+    "CauseExplanation", "Explanation",
+    # Loop
+    "StepResult", "step", "run",
+]

margin/algebra.py

@@ -0,0 +1,177 @@
+"""
+Uncertainty propagation through arithmetic operations.
+
+Correlated values (shared provenance) combine linearly (conservative).
+Independent values combine in quadrature.
+"""
+
+import math
+from datetime import datetime
+from typing import Optional
+
+from .uncertain import UncertainValue, Source
+from .validity import Validity
+from .confidence import Confidence
+from .provenance import new_id, are_correlated
+
+
+def _propagated_validity(inputs: list[UncertainValue]) -> Validity:
+    """Conservative validity: latest measurement, shortest halflife."""
+    if not inputs:
+        return Validity.static()
+
+    latest = max(inputs, key=lambda v: v.validity.measured_at)
+    halflives = [v.validity.halflife for v in inputs if v.validity.halflife]
+    shortest = min(halflives) if halflives else None
+
+    if shortest:
+        return Validity.decaying(shortest, latest.validity.measured_at)
+    return Validity.static(latest.validity.measured_at)
+
+
+def add(a: UncertainValue, b: UncertainValue) -> UncertainValue:
+    """Add two uncertain values with correct uncertainty propagation."""
+    aa, bb = a.to_absolute(), b.to_absolute()
+    if are_correlated(a.provenance, b.provenance):
+        unc = aa.uncertainty + bb.uncertainty
+    else:
+        unc = math.sqrt(aa.uncertainty**2 + bb.uncertainty**2)
+    return UncertainValue(
+        point=aa.point + bb.point,
+        uncertainty=unc,
+        source=Source.PROPAGATED,
+        validity=_propagated_validity([a, b]),
+        provenance=list(set(a.provenance + b.provenance + [new_id()])),
+    )
+
+
+def subtract(a: UncertainValue, b: UncertainValue) -> UncertainValue:
+    """Subtract two uncertain values."""
+    aa, bb = a.to_absolute(), b.to_absolute()
+    if are_correlated(a.provenance, b.provenance):
+        unc = aa.uncertainty + bb.uncertainty
+    else:
+        unc = math.sqrt(aa.uncertainty**2 + bb.uncertainty**2)
+    return UncertainValue(
+        point=aa.point - bb.point,
+        uncertainty=unc,
+        source=Source.PROPAGATED,
+        validity=_propagated_validity([a, b]),
+        provenance=list(set(a.provenance + b.provenance + [new_id()])),
+    )
+
+
+def multiply(a: UncertainValue, b: UncertainValue) -> UncertainValue:
+    """Multiply two uncertain values (relative uncertainties combine).
+
+    When either operand is zero, relative uncertainty is undefined so we
+    fall back to absolute propagation: |b|*σ_a + |a|*σ_b (linear, safe).
+    """
+    product = a.point * b.point
+    prov = list(set(a.provenance + b.provenance + [new_id()]))
+
+    if a.point == 0 or b.point == 0:
+        aa, bb = a.to_absolute(), b.to_absolute()
+        unc = abs(b.point) * aa.uncertainty + abs(a.point) * bb.uncertainty
+        return UncertainValue(
+            point=product, uncertainty=unc,
+            source=Source.PROPAGATED,
+            validity=_propagated_validity([a, b]),
+            provenance=prov,
+        )
+
+    ar, br = a.to_relative(), b.to_relative()
+    if are_correlated(a.provenance, b.provenance):
+        unc = ar.uncertainty + br.uncertainty
+    else:
+        unc = math.sqrt(ar.uncertainty**2 + br.uncertainty**2)
+    return UncertainValue(
+        point=product, uncertainty=unc, relative=True,
+        source=Source.PROPAGATED,
+        validity=_propagated_validity([a, b]),
+        provenance=prov,
+    )
+
+
+def divide(a: UncertainValue, b: UncertainValue) -> UncertainValue:
+    """Divide two uncertain values."""
+    if b.point == 0:
+        raise ValueError("Division by zero")
+    ar, br = a.to_relative(), b.to_relative()
+    if are_correlated(a.provenance, b.provenance):
+        unc = ar.uncertainty + br.uncertainty
+    else:
+        unc = math.sqrt(ar.uncertainty**2 + br.uncertainty**2)
+    return UncertainValue(
+        point=ar.point / br.point,
+        uncertainty=unc,
+        relative=True,
+        source=Source.PROPAGATED,
+        validity=_propagated_validity([a, b]),
+        provenance=list(set(a.provenance + b.provenance + [new_id()])),
+    )
+
+
+def scale(value: UncertainValue, factor: float) -> UncertainValue:
+    """Scale by an exact constant. Preserves provenance without growth."""
+    return UncertainValue(
+        point=value.point * factor,
+        uncertainty=value.uncertainty * abs(factor),
+        relative=value.relative,
+        source=value.source,
+        validity=value.validity,
+        provenance=list(value.provenance),
+    )
+
+
+def compare(value: UncertainValue, threshold: float, at_time: Optional[datetime] = None) -> Confidence:
+    """
+    Compare an uncertain value to a threshold. Returns a Confidence tier
+    based on how much the uncertainty interval overlaps the threshold.
+    """
+    at_time = at_time or datetime.now()
+    u = value.absolute_uncertainty(at_time)
+    lower = value.point - u
+    upper = value.point + u
+    width = 2 * u
+
+    if lower < threshold < upper:
+        return Confidence.INDETERMINATE
+
+    gap = (lower - threshold) if threshold <= lower else (threshold - upper)
+    if width <= 0:
+        return Confidence.CERTAIN
+
+    ratio = gap / width
+    if ratio >= 0.5:
+        return Confidence.CERTAIN
+    elif ratio >= 0.1:
+        return Confidence.HIGH
+    elif ratio >= 0.05:
+        return Confidence.MODERATE
+    else:
+        return Confidence.LOW
+
+
+def weighted_average(values: list[UncertainValue], weights: Optional[list[float]] = None) -> UncertainValue:
+    """
+    Weighted average. Defaults to inverse-variance weighting.
+    """
+    if not values:
+        raise ValueError("Empty list")
+    if len(values) == 1:
+        return values[0]
+
+    if weights is None:
+        variances = [v.to_absolute().uncertainty**2 for v in values]
+        total = sum(1/v for v in variances if v > 0)
+        if total == 0:
+            weights = [1.0 / len(values)] * len(values)
+        else:
+            weights = [(1/v) / total for v in variances]
+
+    result = None
+    for v, w in zip(values, weights):
+        s = scale(v, w)
+        result = add(result, s) if result else s
+    return result

margin/bridge.py

@@ -0,0 +1,205 @@
+"""
+Bridge between the algebra layer (UncertainValue) and the health layer
+(Observation, Expression).
+
+This connects the two halves of the library: uncertain measurements flow
+into typed health classifications, and the uncertainty informs the
+confidence tier automatically.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Optional
+
+from .uncertain import UncertainValue, Source
+from .validity import Validity
+from .confidence import Confidence
+from .health import Health, Thresholds, classify
+from .observation import Observation, Correction, Expression, Op, Parser
+from .algebra import compare, subtract
+
+
+def observe(
+    name: str,
+    value: UncertainValue,
+    baseline: UncertainValue,
+    thresholds: Thresholds,
+    correction_magnitude: float = 0.0,
+    at_time: Optional[datetime] = None,
+) -> Observation:
+    """
+    Create a typed Observation from an UncertainValue.
+
+    The confidence tier is derived automatically by comparing the value
+    against the thresholds using the algebra's `compare()` — the
+    uncertainty interval determines whether the call is CERTAIN, HIGH,
+    MODERATE, LOW, or INDETERMINATE.
+
+    Args:
+        name:        component identifier
+        value:       the uncertain measurement
+        baseline:    expected healthy value (as UncertainValue)
+        thresholds:  classification boundaries
+        correction_magnitude: size of active correction (for RECOVERING)
+        at_time:     evaluation time (defaults to now)
+    """
+    at_time = at_time or datetime.now()
+
+    # Derive confidence from how the uncertainty interval relates to the
+    # intact threshold — the critical decision boundary
+    confidence = compare(value, thresholds.intact, at_time)
+
+    correcting = correction_magnitude >= thresholds.active_min
+    health = classify(value.point, confidence, correcting, thresholds)
+
+    return Observation(
+        name=name,
+        health=health,
+        value=value.point,
+        baseline=baseline.point,
+        confidence=confidence,
+        higher_is_better=thresholds.higher_is_better,
+        provenance=list(value.provenance),
+        measured_at=at_time,
+    )
+
+
+def observe_many(
+    values: dict[str, UncertainValue],
+    baselines: dict[str, UncertainValue],
+    thresholds: Thresholds,
+    component_thresholds: Optional[dict[str, Thresholds]] = None,
+    correction_magnitude: float = 0.0,
+    alpha: float = 0.0,
+    label: str = "",
+    step: Optional[int] = None,
+    at_time: Optional[datetime] = None,
+) -> Expression:
+    """
+    Create a typed Expression from a dict of UncertainValues.
+
+    Like Parser.parse() but takes UncertainValues instead of raw floats,
+    so confidence is derived from the uncertainty rather than defaulting
+    to MODERATE.
+
+    Args:
+        values:      {name: UncertainValue} measurements
+        baselines:   {name: UncertainValue} expected healthy values
+        thresholds:  default classification boundaries
+        component_thresholds: per-component overrides
+        correction_magnitude: size of active correction
+        alpha:       correction intensity coefficient
+        label:       optional label for the expression
+        step:        optional sequence index
+        at_time:     evaluation time (defaults to now)
+    """
+    at_time = at_time or datetime.now()
+    component_thresholds = component_thresholds or {}
+
+    observations = []
+    for name, uv in values.items():
+        bl = baselines.get(name, uv)
+        ct = component_thresholds.get(name, thresholds)
+        obs = observe(name, uv, bl, ct, correction_magnitude, at_time)
+        observations.append(obs)
+
+    # Build a temporary Parser to reuse _classify_op logic
+    corrections = []
+    if observations:
+        raw_values = {name: uv.point for name, uv in values.items()}
+        raw_baselines = {name: baselines.get(name, uv).point for name, uv in values.items()}
+        temp_parser = Parser(
+            baselines=raw_baselines,
+            thresholds=thresholds,
+            component_thresholds=component_thresholds,
+        )
+        target, op = temp_parser._classify_op(raw_values, correction_magnitude)
+
+        if op != Op.NOOP and target:
+            degraded_names = [o.name for o in observations
+                              if o.health in (Health.DEGRADED, Health.ABLATED, Health.RECOVERING)]
+            prov = []
+            for o in observations:
+                if o.name == target:
+                    prov = list(o.provenance)
+                    break
+            corrections.append(Correction(
+                target=target, op=op,
+                alpha=alpha,
+                magnitude=correction_magnitude,
+                triggered_by=degraded_names,
+                provenance=prov,
+            ))
+
+    net_conf = min(
+        (o.confidence for o in observations),
+        default=Confidence.INDETERMINATE,
+    )
+
+    return Expression(
+        observations=observations,
+        corrections=corrections,
+        confidence=net_conf,
+        label=label,
+        step=step,
+    )
+
+
+# Confidence → approximate absolute uncertainty mapping.
+# These are fractions of the value used as uncertainty estimates
+# when reconstructing an UncertainValue from an Observation.
+_CONFIDENCE_TO_UNCERTAINTY = {
+    Confidence.CERTAIN: 0.01,
+    Confidence.HIGH: 0.05,
+    Confidence.MODERATE: 0.10,
+    Confidence.LOW: 0.25,
+    Confidence.INDETERMINATE: 0.50,
+}
+
+
+def to_uncertain(obs: Observation) -> UncertainValue:
+    """
+    Reconstruct an UncertainValue from an Observation.
+
+    Since Observations don't carry explicit uncertainty, it is inferred
+    from the confidence tier: CERTAIN → 1% of |value|, HIGH → 5%,
+    MODERATE → 10%, LOW → 25%, INDETERMINATE → 50%.
+
+    This closes the loop: observe() goes algebra→health, to_uncertain()
+    goes health→algebra.
+    """
+    frac = _CONFIDENCE_TO_UNCERTAINTY.get(obs.confidence, 0.10)
+    unc = frac * abs(obs.value) if obs.value != 0 else frac
+
+    validity = Validity.static(obs.measured_at) if obs.measured_at else Validity.static()
+
+    return UncertainValue(
+        point=obs.value,
+        uncertainty=unc,
+        source=Source.MODELED,
+        validity=validity,
+        provenance=list(obs.provenance) if obs.provenance else None,
+    )
+
+
+def delta(
+    name: str,
+    before: UncertainValue,
+    after: UncertainValue,
+    baseline: UncertainValue,
+    thresholds: Thresholds,
+    at_time: Optional[datetime] = None,
+) -> tuple[Observation, Observation, UncertainValue]:
+    """
+    Compute typed before/after observations and the uncertain difference.
+
+    Returns (obs_before, obs_after, diff) where diff is an UncertainValue
+    representing the change with correctly propagated uncertainty.
+    Useful for building Records with full algebra backing.
+    """
+    at_time = at_time or datetime.now()
+    obs_before = observe(name, before, baseline, thresholds, at_time=at_time)
+    obs_after = observe(name, after, baseline, thresholds, at_time=at_time)
+    diff = subtract(after, before)
+    return obs_before, obs_after, diff

margin/calibrate.py

@@ -0,0 +1,182 @@
+"""
+Threshold derivation from historical data.
+
+Takes a set of "known healthy" measurements and derives baselines and
+thresholds automatically.
+"""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+from typing import Optional
+
+from .health import Thresholds
+from .observation import Parser
+
+
+@dataclass
+class CalibrationResult:
+    """
+    Output of calibrate(): derived baseline and thresholds for one component.
+
+    baseline:     mean of healthy measurements
+    std:          standard deviation of healthy measurements
+    n_samples:    number of measurements used
+    thresholds:   derived Thresholds object
+    """
+    baseline: float
+    std: float
+    n_samples: int
+    thresholds: Thresholds
+
+    def to_dict(self) -> dict:
+        return {
+            "baseline": round(self.baseline, 6),
+            "std": round(self.std, 6),
+            "n_samples": self.n_samples,
+            "intact": self.thresholds.intact,
+            "ablated": self.thresholds.ablated,
+            "higher_is_better": self.thresholds.higher_is_better,
+        }
+
+
+def calibrate(
+    values: list[float],
+    higher_is_better: bool = True,
+    intact_fraction: float = 0.70,
+    ablated_fraction: float = 0.30,
+    active_min: float = 0.05,
+) -> CalibrationResult:
+    """
+    Derive a baseline and thresholds from known-healthy measurements.
+
+    Takes a list of measurements collected when the component was operating
+    normally, and derives:
+    - baseline: mean of the measurements
+    - intact threshold: intact_fraction * baseline
+    - ablated threshold: ablated_fraction * baseline
+
+    Args:
+        values:           list of healthy-state measurements
+        higher_is_better: polarity
+        intact_fraction:  fraction of baseline for intact threshold (default 0.70)
+        ablated_fraction: fraction of baseline for ablated threshold (default 0.30)
+        active_min:       minimum correction magnitude for "active"
+
+    For higher_is_better=True:
+        intact  = baseline * intact_fraction  (e.g. 70% of healthy mean)
+        ablated = baseline * ablated_fraction  (e.g. 30% of healthy mean)
+
+    For higher_is_better=False:
+        intact  = baseline * (1 + (1 - intact_fraction))   (e.g. 130% of healthy mean)
+        ablated = baseline * (1 + (1 - ablated_fraction))   (e.g. 170% of healthy mean)
+        This puts the "bad" direction above baseline for lower-is-better metrics.
+    """
+    if not values:
+        raise ValueError("Cannot calibrate from empty list")
+
+    n = len(values)
+    baseline = sum(values) / n
+
+    if baseline == 0:
+        raise ValueError("Cannot calibrate from zero baseline — thresholds would be degenerate")
+    if higher_is_better and baseline < 0:
+        raise ValueError(
+            f"Cannot calibrate higher_is_better=True with negative baseline ({baseline}). "
+            "Fraction-based thresholds invert for negative values. "
+            "Use higher_is_better=False or shift your measurements to be positive.")
+
+    variance = sum((v - baseline) ** 2 for v in values) / max(n - 1, 1)
+    std = math.sqrt(variance)
+
+    if higher_is_better:
+        intact = baseline * intact_fraction
+        ablated = baseline * ablated_fraction
+    else:
+        # For lower-is-better, thresholds are above baseline (unhealthy direction).
+        # Uses abs(baseline) so the math works for both positive and negative baselines.
+        intact = baseline + abs(baseline) * (1 - intact_fraction)
+        ablated = baseline + abs(baseline) * (1 - ablated_fraction)
+
+    thresholds = Thresholds(
+        intact=round(intact, 6),
+        ablated=round(ablated, 6),
+        higher_is_better=higher_is_better,
+        active_min=active_min,
+    )
+
+    return CalibrationResult(
+        baseline=baseline,
+        std=std,
+        n_samples=n,
+        thresholds=thresholds,
+    )
+
+
+def calibrate_many(
+    component_values: dict[str, list[float]],
+    polarities: Optional[dict[str, bool]] = None,
+    intact_fraction: float = 0.70,
+    ablated_fraction: float = 0.30,
+    active_min: float = 0.05,
+) -> tuple[dict[str, float], dict[str, Thresholds]]:
+    """
+    Calibrate multiple components at once. Returns (baselines, thresholds)
+    ready to pass directly to Parser().
+
+    Args:
+        component_values: {name: [healthy_measurements]}
+        polarities:       {name: higher_is_better} (defaults to True)
+        intact_fraction:  fraction of baseline for intact threshold
+        ablated_fraction: fraction of baseline for ablated threshold
+        active_min:       minimum correction magnitude
+
+    Returns:
+        (baselines_dict, thresholds_dict) suitable for:
+            Parser(baselines=baselines_dict,
+                   thresholds=first_threshold,
+                   component_thresholds=thresholds_dict)
+    """
+    polarities = polarities or {}
+    baselines = {}
+    thresholds = {}
+
+    for name, vals in component_values.items():
+        hib = polarities.get(name, True)
+        result = calibrate(vals, hib, intact_fraction, ablated_fraction, active_min)
+        baselines[name] = result.baseline
+        thresholds[name] = result.thresholds
+
+    return baselines, thresholds
+
+
+def parser_from_calibration(
+    component_values: dict[str, list[float]],
+    polarities: Optional[dict[str, bool]] = None,
+    intact_fraction: float = 0.70,
+    ablated_fraction: float = 0.30,
+    active_min: float = 0.05,
+) -> Parser:
+    """
+    One-shot: calibrate from historical data and return a ready-to-use Parser.
+
+    Uses the first component's thresholds as the default, with all others
+    as component_thresholds overrides.
+    """
+    baselines, thresh_dict = calibrate_many(
+        component_values, polarities, intact_fraction, ablated_fraction, active_min,
+    )
+
+    names = list(thresh_dict.keys())
+    if not names:
+        raise ValueError("No components to calibrate")
+
+    default_thresholds = thresh_dict[names[0]]
+    component_thresholds = {n: t for n, t in thresh_dict.items() if n != names[0]}
+
+    return Parser(
+        baselines=baselines,
+        thresholds=default_thresholds,
+        component_thresholds=component_thresholds,
+    )