margin 0.1.0__tar.gz

margin-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Seth C
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

margin-0.1.0/PKG-INFO

@@ -0,0 +1,138 @@
+Metadata-Version: 2.4
+Name: margin
+Version: 0.1.0
+Summary: Typed health classification, uncertainty algebra, and correction auditing for any system that measures things and needs to explain what happened.
+Author: Seth C
+License: MIT
+Project-URL: Homepage, https://github.com/sethc5/margin
+Project-URL: Repository, https://github.com/sethc5/margin
+Project-URL: Issues, https://github.com/sethc5/margin/issues
+Keywords: health,monitoring,uncertainty,observability,typed,classification,threshold,polarity,correction,audit,ledger,policy
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: System :: Monitoring
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# margin
+
+**Typed health classification for systems that measure things.**
+
+Every system with health bars, thresholds, alerts, or status dashboards solves the same problem: take a number, decide if it's healthy, correct it if it isn't, explain what happened. Margin is that pattern, typed once, with the polarity bug fixed.
+
+```python
+from margin import Parser, Thresholds
+
+parser = Parser(
+    baselines={"throughput": 500.0, "error_rate": 0.002},
+    thresholds=Thresholds(intact=400.0, ablated=150.0),
+    component_thresholds={
+        "error_rate": Thresholds(intact=0.005, ablated=0.05, higher_is_better=False),
+    },
+)
+
+expr = parser.parse({"throughput": 480.0, "error_rate": 0.03})
+print(expr.to_string())
+# [throughput:INTACT(-0.04σ)] [error_rate:DEGRADED(-14.00σ)]
+```
+
+Throughput and error rate on the same scale. One is higher-is-better, the other is lower-is-better. Both classified correctly. Sigma-normalised so you can compare them.
+
+## Install
+
+```bash
+pip install margin
+```
+
+Zero dependencies. Pure Python. 3.10+.
+
+## What it does
+
+A number comes in. Margin gives it:
+
+- **Health** — INTACT / DEGRADED / ABLATED / RECOVERING / OOD
+- **Polarity** — higher-is-better or lower-is-better, handled correctly everywhere
+- **Sigma** — dimensionless deviation from baseline, always positive = healthier
+- **Confidence** — how much the uncertainty interval overlaps the threshold
+- **Provenance** — where this value came from, for correlation detection
+- **Validity** — how the measurement ages (static, decaying, event-invalidated)
+
+Then the correction loop:
+
+- **Policy** — typed rules that decide what to do (RESTORE / SUPPRESS / AMPLIFY)
+- **Constraints** — alpha clamping, cooldown, rate limiting
+- **Escalation** — LOG / ALERT / HALT when the policy can't act
+- **Contract** — typed success criteria ("reach INTACT within 5 steps")
+- **Causal** — dependency graphs ("api is DEGRADED because db is ABLATED")
+- **Ledger** — full audit trail of every correction, serializable, replayable
+
+All in one call:
+
+```python
+from margin import step
+
+result = step(expression, policy, ledger, graph, contract)
+# result.correction    — what to do
+# result.explanations  — why it happened
+# result.decision      — which rule matched, full trace
+# result.contract      — are we meeting our goals?
+```
+
+## The polarity bug
+
+Every health system you've written has this bug. You check `if value >= threshold` and it works for throughput. Then you add error rate monitoring and the same check says 15% error rate is "healthy" because 0.15 >= 0.02.
+
+Margin handles both polarities:
+
+```python
+# Higher is better (throughput, signal strength)
+Thresholds(intact=80.0, ablated=30.0)
+
+# Lower is better (error rate, latency)
+Thresholds(intact=0.02, ablated=0.10, higher_is_better=False)
+```
+
+One flag. Threads through every comparison, every sigma calculation, every correction decision, every recovery ratio. You never think about it again.
+
+## Auto-calibrate from data
+
+Don't guess thresholds. Derive them from healthy measurements:
+
+```python
+from margin import parser_from_calibration
+
+parser = parser_from_calibration(
+    {"rps": [490, 510, 505, 495], "latency": [48, 52, 50, 51]},
+    polarities={"latency": False},
+)
+```
+
+## Five layers
+
+| Layer | Question | Key types |
+|---|---|---|
+| **Foundation** | What was measured? | `Health`, `Observation`, `Expression`, `UncertainValue` |
+| **Observability** | What changed? When will it cross? | `diff()`, `forecast()`, `track()`, `calibrate()` |
+| **Policy** | What should we do? | `PolicyRule`, `Action`, `Constraint`, `Escalation` |
+| **Contract** | Are we meeting our goals? | `HealthTarget`, `SustainHealth`, `RecoveryThreshold` |
+| **Causal** | Why did this happen? | `CausalGraph`, `CausalLink`, `Explanation` |
+
+Plus `step()` and `run()` to orchestrate all five in one call.
+
+## Docs
+
+Full specification: [margin-language.md](margin/margin-language.md)
+
+## License
+
+MIT

margin-0.1.0/README.md

@@ -0,0 +1,112 @@
+# margin
+
+**Typed health classification for systems that measure things.**
+
+Every system with health bars, thresholds, alerts, or status dashboards solves the same problem: take a number, decide if it's healthy, correct it if it isn't, explain what happened. Margin is that pattern, typed once, with the polarity bug fixed.
+
+```python
+from margin import Parser, Thresholds
+
+parser = Parser(
+    baselines={"throughput": 500.0, "error_rate": 0.002},
+    thresholds=Thresholds(intact=400.0, ablated=150.0),
+    component_thresholds={
+        "error_rate": Thresholds(intact=0.005, ablated=0.05, higher_is_better=False),
+    },
+)
+
+expr = parser.parse({"throughput": 480.0, "error_rate": 0.03})
+print(expr.to_string())
+# [throughput:INTACT(-0.04σ)] [error_rate:DEGRADED(-14.00σ)]
+```
+
+Throughput and error rate on the same scale. One is higher-is-better, the other is lower-is-better. Both classified correctly. Sigma-normalised so you can compare them.
+
+## Install
+
+```bash
+pip install margin
+```
+
+Zero dependencies. Pure Python. 3.10+.
+
+## What it does
+
+A number comes in. Margin gives it:
+
+- **Health** — INTACT / DEGRADED / ABLATED / RECOVERING / OOD
+- **Polarity** — higher-is-better or lower-is-better, handled correctly everywhere
+- **Sigma** — dimensionless deviation from baseline, always positive = healthier
+- **Confidence** — how much the uncertainty interval overlaps the threshold
+- **Provenance** — where this value came from, for correlation detection
+- **Validity** — how the measurement ages (static, decaying, event-invalidated)
+
+Then the correction loop:
+
+- **Policy** — typed rules that decide what to do (RESTORE / SUPPRESS / AMPLIFY)
+- **Constraints** — alpha clamping, cooldown, rate limiting
+- **Escalation** — LOG / ALERT / HALT when the policy can't act
+- **Contract** — typed success criteria ("reach INTACT within 5 steps")
+- **Causal** — dependency graphs ("api is DEGRADED because db is ABLATED")
+- **Ledger** — full audit trail of every correction, serializable, replayable
+
+All in one call:
+
+```python
+from margin import step
+
+result = step(expression, policy, ledger, graph, contract)
+# result.correction    — what to do
+# result.explanations  — why it happened
+# result.decision      — which rule matched, full trace
+# result.contract      — are we meeting our goals?
+```
+
+## The polarity bug
+
+Every health system you've written has this bug. You check `if value >= threshold` and it works for throughput. Then you add error rate monitoring and the same check says 15% error rate is "healthy" because 0.15 >= 0.02.
+
+Margin handles both polarities:
+
+```python
+# Higher is better (throughput, signal strength)
+Thresholds(intact=80.0, ablated=30.0)
+
+# Lower is better (error rate, latency)
+Thresholds(intact=0.02, ablated=0.10, higher_is_better=False)
+```
+
+One flag. Threads through every comparison, every sigma calculation, every correction decision, every recovery ratio. You never think about it again.
+
+## Auto-calibrate from data
+
+Don't guess thresholds. Derive them from healthy measurements:
+
+```python
+from margin import parser_from_calibration
+
+parser = parser_from_calibration(
+    {"rps": [490, 510, 505, 495], "latency": [48, 52, 50, 51]},
+    polarities={"latency": False},
+)
+```
+
+## Five layers
+
+| Layer | Question | Key types |
+|---|---|---|
+| **Foundation** | What was measured? | `Health`, `Observation`, `Expression`, `UncertainValue` |
+| **Observability** | What changed? When will it cross? | `diff()`, `forecast()`, `track()`, `calibrate()` |
+| **Policy** | What should we do? | `PolicyRule`, `Action`, `Constraint`, `Escalation` |
+| **Contract** | Are we meeting our goals? | `HealthTarget`, `SustainHealth`, `RecoveryThreshold` |
+| **Causal** | Why did this happen? | `CausalGraph`, `CausalLink`, `Explanation` |
+
+Plus `step()` and `run()` to orchestrate all five in one call.
+
+## Docs
+
+Full specification: [margin-language.md](margin/margin-language.md)
+
+## License
+
+MIT

margin-0.1.0/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-0.1.0/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