margin 0.9.29__tar.gz → 0.9.30__tar.gz

{margin-0.9.29/margin.egg-info → margin-0.9.30}/PKG-INFO

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

@@ -120,6 +120,9 @@ from .intent import (
 # Loop
 from .loop import StepResult, step, run, FullStepResult, full_step
 
+# Issue (diagnostics)
+from .issue import Issue, IssueLevel, IssueCode, IssueBuffer, ISSUE_SEVERITY
+
 # Flow
 from .flow import Flow, Stage, Guidance, FlowResult, GUIDANCE_SEVERITY
 
@@ -193,6 +196,8 @@ __all__ = [
     "save_monitor", "load_monitor", "replay", "replay_csv",
     # Loop
     "StepResult", "step", "run", "FullStepResult", "full_step",
+    # Issue (diagnostics)
+    "Issue", "IssueLevel", "IssueCode", "IssueBuffer", "ISSUE_SEVERITY",
     # Flow
     "Flow", "Stage", "Guidance", "FlowResult", "GUIDANCE_SEVERITY",
     # margin-poc compat aliases

{margin-0.9.29 → margin-0.9.30}/margin/flow.py

@@ -61,6 +61,7 @@ from enum import Enum
 from typing import Callable, Dict, List, Optional
 
 from .health import Health
+from .issue import Issue, IssueBuffer, IssueCode, IssueLevel
 from .observation import Expression, Parser
 from .streaming import Monitor
 
@@ -150,6 +151,11 @@ class FlowResult:
     expression: Optional[Expression]
     guidance: Guidance
     reason: str
+    issues: List[Issue] = None  # type: ignore[assignment]
+
+    def __post_init__(self):
+        if self.issues is None:
+            self.issues = []
 
     def to_atom(self) -> str:
         """
@@ -166,15 +172,34 @@ class FlowResult:
             "flow[5/5]"                                    # complete
         """
         prefix = f"flow:{self.flow_label}" if self.flow_label else "flow"
+        suffix = ""
+        if self.issues:
+            # Annotate with issue counts by level, in severity order.
+            marks = []
+            from .issue import IssueLevel as _IL
+            counts = {l: 0 for l in _IL}
+            for iss in self.issues:
+                counts[iss.level] += 1
+            level_marks = [
+                (_IL.FATAL, "‼"),
+                (_IL.ERROR, "!"),
+                (_IL.WARNING, "⚠"),
+                (_IL.INFO, "·"),
+            ]
+            for lvl, m in level_marks:
+                if counts[lvl] > 0:
+                    marks.append(f"{m}{counts[lvl]}")
+            if marks:
+                suffix = " (" + " ".join(marks) + ")"
         if self.guidance == Guidance.COMPLETE:
-            return f"{prefix}[{self.total_stages}/{self.total_stages}]"
+            return f"{prefix}[{self.total_stages}/{self.total_stages}]{suffix}"
         return (
             f"{prefix}:{self.stage}[{self.stage_index + 1}/{self.total_stages}]"
-            f" → {self.guidance.value}"
+            f" → {self.guidance.value}{suffix}"
         )
 
     def to_dict(self) -> dict:
-        return {
+        d = {
             "flow_label": self.flow_label,
             "stage": self.stage,
             "stage_index": self.stage_index,
@@ -183,6 +208,9 @@ class FlowResult:
             "reason": self.reason,
             "expression": self.expression.to_dict() if self.expression else None,
         }
+        if self.issues:
+            d["issues"] = [i.to_dict() for i in self.issues]
+        return d
 
     def __repr__(self) -> str:
         return f"FlowResult({self.to_atom()} — {self.reason})"
@@ -254,6 +282,21 @@ class Flow:
         }
         self._transitions: List[dict] = []
         self._entered_at: datetime = datetime.now()
+        self._issues: IssueBuffer = IssueBuffer()
+
+        # Emit INFO if a stage has no predicates at all (will HOLD forever)
+        for s in self.stages:
+            if (s.advance_when is None and s.retry_when is None
+                    and s.escalate_when is None and s.rollback_when is None):
+                self._issues.emit(
+                    IssueLevel.INFO,
+                    IssueCode.NO_PREDICATES,
+                    detail=(
+                        f"stage {s.name!r} has no predicates; will only leave "
+                        "via explicit advance()/rollback()."
+                    ),
+                    component=s.name,
+                )
 
     # ------------------------------------------------------------------
     # Inspection
@@ -286,6 +329,15 @@ class Flow:
         """History of stage transitions."""
         return list(self._transitions)
 
+    @property
+    def issues(self) -> IssueBuffer:
+        """IssueBuffer of diagnostics this Flow has emitted.  Harvestable."""
+        return self._issues
+
+    def diagnose(self, n: int = 10) -> dict:
+        """Dashboard-friendly summary of recent issues.  See IssueBuffer.diagnose."""
+        return self._issues.diagnose(n)
+
     # ------------------------------------------------------------------
     # Observation
     # ------------------------------------------------------------------
@@ -296,7 +348,14 @@ class Flow:
 
         ``values`` and any kwargs are forwarded to ``Monitor.update()``, so
         confidences, absences, and provenance all pass through.
+
+        Hard-fail semantics: if the underlying Monitor raises, the issue
+        is captured as FATAL on the Flow buffer and re-raised.  Predicate
+        exceptions are caught (not re-raised), recorded as ERROR issues,
+        and guidance degrades to HOLD with a ``predicate failure`` reason.
         """
+        import traceback as _tb
+
         if self.is_complete:
             return FlowResult(
                 flow_label=self.label,
@@ -306,12 +365,28 @@ class Flow:
                 expression=None,
                 guidance=Guidance.COMPLETE,
                 reason="all stages complete",
+                issues=[],
             )
 
         stage = self.current
         monitor = self._monitors[stage.name]
-        expr = monitor.update(values, **kw)
-        guidance, reason = self._classify(stage, expr)
+        try:
+            expr = monitor.update(values, **kw)
+        except Exception as _e:
+            self._issues.emit(
+                IssueLevel.FATAL,
+                IssueCode.INTERNAL_ERROR,
+                detail=f"Monitor.update raised in stage {stage.name!r}: {_e}",
+                component=stage.name,
+                exc_type=type(_e).__name__,
+                traceback=_tb.format_exc(),
+            )
+            raise
+
+        # Collect issues produced this step: Parser's issues are on expr,
+        # predicate failures are emitted during _classify.
+        step_issues: List[Issue] = list(expr.issues)
+        guidance, reason = self._classify(stage, expr, step_issues)
 
         return FlowResult(
             flow_label=self.label,
@@ -321,19 +396,73 @@ class Flow:
             expression=expr,
             guidance=guidance,
             reason=reason,
+            issues=step_issues,
         )
 
-    def _classify(self, stage: Stage, expr: Expression) -> tuple[Guidance, str]:
-        """Evaluate stage predicates in severity order."""
+    def _safe_predicate(
+        self,
+        predicate,
+        expr: Expression,
+        name: str,
+        stage_name: str,
+        collected: List[Issue],
+    ) -> Optional[bool]:
+        """
+        Call a stage predicate, capturing any exception as an ERROR issue.
+        Returns None on failure (distinguishable from False), the bool result
+        on success.  Issues go both on the Flow buffer (for post-mortem) and
+        in ``collected`` (for the FlowResult this step).
+        """
+        try:
+            return bool(predicate(expr))
+        except Exception as _e:
+            import traceback as _tb
+            iss = self._issues.emit(
+                IssueLevel.ERROR,
+                IssueCode.PREDICATE_FAILURE,
+                detail=f"{name} raised in stage {stage_name!r}: {_e}",
+                component=stage_name,
+                predicate=name,
+                exc_type=type(_e).__name__,
+                traceback=_tb.format_exc(),
+            )
+            collected.append(iss)
+            return None
+
+    def _classify(
+        self, stage: Stage, expr: Expression, collected: List[Issue],
+    ) -> tuple[Guidance, str]:
+        """Evaluate stage predicates in severity order, safely."""
         # Highest severity first — a true escalate dominates an advance
-        if stage.escalate_when is not None and stage.escalate_when(expr):
-            return Guidance.ESCALATE, "escalate_when fired"
-        if stage.rollback_when is not None and stage.rollback_when(expr):
-            return Guidance.ROLLBACK, "rollback_when fired"
-        if stage.advance_when is not None and stage.advance_when(expr):
-            return Guidance.ADVANCE, "advance_when fired"
-        if stage.retry_when is not None and stage.retry_when(expr):
-            return Guidance.RETRY, "retry_when fired"
+        if stage.escalate_when is not None:
+            fired = self._safe_predicate(
+                stage.escalate_when, expr, "escalate_when", stage.name, collected,
+            )
+            if fired:
+                return Guidance.ESCALATE, "escalate_when fired"
+        if stage.rollback_when is not None:
+            fired = self._safe_predicate(
+                stage.rollback_when, expr, "rollback_when", stage.name, collected,
+            )
+            if fired:
+                return Guidance.ROLLBACK, "rollback_when fired"
+        if stage.advance_when is not None:
+            fired = self._safe_predicate(
+                stage.advance_when, expr, "advance_when", stage.name, collected,
+            )
+            if fired:
+                return Guidance.ADVANCE, "advance_when fired"
+        if stage.retry_when is not None:
+            fired = self._safe_predicate(
+                stage.retry_when, expr, "retry_when", stage.name, collected,
+            )
+            if fired:
+                return Guidance.RETRY, "retry_when fired"
+
+        # If any predicate raised, surface that in the reason so callers
+        # notice degraded guidance without having to inspect the buffer.
+        if any(i.code == IssueCode.PREDICATE_FAILURE for i in collected):
+            return Guidance.HOLD, "predicate failure — see issues"
 
         # Fallback classification using observation health alone
         if any(o.health == Health.ABLATED for o in expr.observations):
@@ -385,11 +514,12 @@ class Flow:
         return self._status_result("rolled back")
 
     def reset(self) -> None:
-        """Reset to the first stage.  Clears all monitors and transitions."""
+        """Reset to the first stage.  Clears monitors, transitions, and issues."""
         self._index = 0
         self._monitors = {self.stages[0].name: self.stages[0].create_monitor()}
         self._transitions = []
         self._entered_at = datetime.now()
+        self._issues.clear()
 
     def _status_result(self, reason: str) -> FlowResult:
         if self.is_complete:

margin-0.9.30/margin/issue.py

@@ -0,0 +1,325 @@
+"""
+Issue: typed diagnostics for the margin machinery itself.
+
+Where Health describes the state of what we're observing, and Absence
+describes why a value is missing, Issue describes something the library
+noticed about its own operation: a misconfiguration, a degraded
+assumption, a recovered failure, a near-crash.
+
+Design constraints
+------------------
+
+1. **Usable, not just aesthetic.**  Issues accumulate on long-lived
+   objects (``Monitor._issues``, ``Flow._issues``) and are attached to
+   per-call results (``Expression.issues``, ``FlowResult.issues``).
+   Consumers never have to construct their own Issues — the library
+   emits them at known sites.
+
+2. **Harvestable on hard fail.**  Issues are added to the buffer
+   *before* exceptions propagate, using ``try / finally`` patterns in
+   the callers.  Even a FATAL internal error leaves the full recent
+   issue history intact for post-mortem inspection.
+
+3. **Typed, not strings.**  Issue.code is a short stable identifier
+   (``BASELINE_MISSING``, ``PREDICATE_FAILURE``) that consumers can
+   filter and aggregate programmatically — the same way DriftState
+   or Health are typed.
+
+Exceptions vs. Issues
+---------------------
+
+- **Exceptions** mean "your code is broken."  Invalid arguments, wrong
+  types, structural errors.  These raise loudly.
+- **Issues** mean "something worth noting happened in the system we
+  observe or in how we're observing it."  Missing baselines,
+  insufficient samples, near-zero std, recovered predicate failures.
+  These accumulate.
+
+Convenience: ``diagnose()`` on Monitor/Flow returns a grouped summary
+suitable for dashboards or log aggregation.
+"""
+
+from __future__ import annotations
+
+from collections import deque
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import Enum
+from typing import Any, Deque, Dict, List, Optional
+
+
+# -----------------------------------------------------------------------
+# Level
+# -----------------------------------------------------------------------
+
+class IssueLevel(Enum):
+    """
+    Severity of an Issue.
+
+    INFO:     something worth noting but expected (insufficient samples yet)
+    WARNING:  degraded assumption (baseline missing, near-zero std)
+    ERROR:    recovered failure (predicate raised, continued on fallback)
+    FATAL:    unrecovered failure (exception re-raised after capture)
+    """
+    INFO = "INFO"
+    WARNING = "WARNING"
+    ERROR = "ERROR"
+    FATAL = "FATAL"
+
+
+ISSUE_SEVERITY: Dict[IssueLevel, int] = {
+    IssueLevel.INFO: 0,
+    IssueLevel.WARNING: 1,
+    IssueLevel.ERROR: 2,
+    IssueLevel.FATAL: 3,
+}
+
+
+# -----------------------------------------------------------------------
+# Issue
+# -----------------------------------------------------------------------
+
+@dataclass
+class Issue:
+    """
+    One diagnostic event from the margin machinery.
+
+    level:      severity
+    code:       short stable identifier (``BASELINE_MISSING``, etc.)
+    component:  optional component name this issue is scoped to
+    detail:     free-text explanation for a human reader
+    at:         timestamp (defaults to now)
+    context:    optional extra fields — traceback, exc type, source, etc.
+    """
+    level: IssueLevel
+    code: str
+    component: Optional[str] = None
+    detail: str = ""
+    at: datetime = field(default_factory=datetime.now)
+    context: Dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict:
+        d: dict = {
+            "level": self.level.value,
+            "code": self.code,
+            "at": self.at.isoformat(),
+        }
+        if self.component is not None:
+            d["component"] = self.component
+        if self.detail:
+            d["detail"] = self.detail
+        if self.context:
+            d["context"] = dict(self.context)
+        return d
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "Issue":
+        return cls(
+            level=IssueLevel(d["level"]),
+            code=d["code"],
+            component=d.get("component"),
+            detail=d.get("detail", ""),
+            at=datetime.fromisoformat(d["at"]) if "at" in d else datetime.now(),
+            context=dict(d.get("context", {})),
+        )
+
+    def to_atom(self) -> str:
+        """Compact string: ``!level[code](component)`` — fits alongside observation atoms."""
+        mark = {"INFO": "·", "WARNING": "⚠", "ERROR": "!", "FATAL": "‼"}[self.level.value]
+        if self.component is not None:
+            return f"{mark}{self.level.value}[{self.code}]({self.component})"
+        return f"{mark}{self.level.value}[{self.code}]"
+
+    def __repr__(self) -> str:
+        comp = f", component={self.component!r}" if self.component is not None else ""
+        return f"Issue({self.level.value}, {self.code}{comp}, {self.detail!r})"
+
+
+# -----------------------------------------------------------------------
+# Buffer
+# -----------------------------------------------------------------------
+
+class IssueBuffer:
+    """
+    Bounded ring buffer of Issues with simple query helpers.
+
+    Lives on long-lived objects (Monitor, Flow) so post-mortem inspection
+    survives exceptions and crashes inside library methods.  Bounded so
+    long-running sessions don't accumulate unbounded memory.
+
+    Default capacity is 1000 issues.  For high-rate production, consider
+    periodically exporting with ``drain()`` and clearing.
+    """
+
+    def __init__(self, max_issues: int = 1000):
+        if max_issues < 1:
+            raise ValueError("max_issues must be >= 1")
+        self.max_issues = max_issues
+        self._issues: Deque[Issue] = deque(maxlen=max_issues)
+
+    # ------------------------------------------------------------------
+    # Writing
+    # ------------------------------------------------------------------
+
+    def add(self, issue: Issue) -> Issue:
+        """Append an issue.  Returns the issue for chained access."""
+        self._issues.append(issue)
+        return issue
+
+    def emit(
+        self,
+        level: IssueLevel,
+        code: str,
+        detail: str = "",
+        component: Optional[str] = None,
+        **context: Any,
+    ) -> Issue:
+        """
+        Construct and append an Issue inline.  Returns the issue.
+
+        Convenient at call sites::
+
+            self._issues.emit(IssueLevel.WARNING, "BASELINE_MISSING",
+                              f"component {name!r} has no baseline",
+                              component=name)
+        """
+        return self.add(Issue(
+            level=level,
+            code=code,
+            component=component,
+            detail=detail,
+            context=dict(context) if context else {},
+        ))
+
+    def clear(self) -> None:
+        self._issues.clear()
+
+    def drain(self) -> List[Issue]:
+        """Remove and return all current issues.  Buffer becomes empty."""
+        out = list(self._issues)
+        self._issues.clear()
+        return out
+
+    # ------------------------------------------------------------------
+    # Reading
+    # ------------------------------------------------------------------
+
+    def __len__(self) -> int:
+        return len(self._issues)
+
+    def __iter__(self):
+        return iter(self._issues)
+
+    def __bool__(self) -> bool:
+        return bool(self._issues)
+
+    def to_list(self) -> List[Issue]:
+        """Snapshot copy of all current issues."""
+        return list(self._issues)
+
+    def tail(self, n: int = 10) -> List[Issue]:
+        """Last ``n`` issues (most recent)."""
+        if n <= 0:
+            return []
+        items = list(self._issues)
+        return items[-n:]
+
+    def by_code(self, code: str) -> List[Issue]:
+        return [i for i in self._issues if i.code == code]
+
+    def by_level(self, level: IssueLevel) -> List[Issue]:
+        return [i for i in self._issues if i.level == level]
+
+    def by_component(self, component: str) -> List[Issue]:
+        return [i for i in self._issues if i.component == component]
+
+    def at_least(self, level: IssueLevel) -> List[Issue]:
+        """All issues with severity >= ``level``."""
+        threshold = ISSUE_SEVERITY[level]
+        return [i for i in self._issues if ISSUE_SEVERITY[i.level] >= threshold]
+
+    # ------------------------------------------------------------------
+    # Summarization
+    # ------------------------------------------------------------------
+
+    def counts(self) -> Dict[str, int]:
+        """Count by level.  Result keys are level string values."""
+        out: Dict[str, int] = {l.value: 0 for l in IssueLevel}
+        for i in self._issues:
+            out[i.level.value] += 1
+        return out
+
+    def diagnose(self, n: int = 10) -> Dict[str, Any]:
+        """
+        Human/dashboard-friendly summary.
+
+        Returns::
+
+            {
+                "total": int,
+                "counts": {"INFO": n, "WARNING": n, "ERROR": n, "FATAL": n},
+                "recent": [Issue, ...],      # last n
+                "codes": {"BASELINE_MISSING": n, ...},   # by code
+            }
+        """
+        codes: Dict[str, int] = {}
+        for i in self._issues:
+            codes[i.code] = codes.get(i.code, 0) + 1
+        return {
+            "total": len(self._issues),
+            "counts": self.counts(),
+            "recent": self.tail(n),
+            "codes": codes,
+        }
+
+    # ------------------------------------------------------------------
+    # Serialization
+    # ------------------------------------------------------------------
+
+    def to_dict(self) -> dict:
+        return {
+            "max_issues": self.max_issues,
+            "issues": [i.to_dict() for i in self._issues],
+        }
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "IssueBuffer":
+        buf = cls(max_issues=d.get("max_issues", 1000))
+        for item in d.get("issues", []):
+            buf.add(Issue.from_dict(item))
+        return buf
+
+    def __repr__(self) -> str:
+        if not self._issues:
+            return "IssueBuffer(empty)"
+        c = self.counts()
+        parts = [f"{k}={v}" for k, v in c.items() if v > 0]
+        return f"IssueBuffer({len(self._issues)}: {', '.join(parts)})"
+
+
+# -----------------------------------------------------------------------
+# Well-known issue codes
+# -----------------------------------------------------------------------
+
+# These are the codes the margin library itself emits.  Users can define
+# their own codes too — they're just strings.  Centralizing the canonical
+# ones here makes them greppable and documentable.
+
+class IssueCode:
+    # Parser
+    BASELINE_MISSING = "BASELINE_MISSING"           # WARNING
+
+    # Monitor
+    INSUFFICIENT_SAMPLES = "INSUFFICIENT_SAMPLES"   # INFO
+    NEAR_ZERO_STD = "NEAR_ZERO_STD"                 # INFO
+
+    # Flow
+    PREDICATE_FAILURE = "PREDICATE_FAILURE"         # ERROR
+    STAGE_ABLATED_ON_ENTRY = "STAGE_ABLATED_ON_ENTRY"  # WARNING
+    NO_PREDICATES = "NO_PREDICATES"                 # INFO
+
+    # Catch-all for exceptions that were captured as issues before re-raise
+    INTERNAL_ERROR = "INTERNAL_ERROR"               # FATAL
+
+    # User-supplied input problems
+    UNKNOWN_COMPONENT = "UNKNOWN_COMPONENT"         # WARNING

{margin-0.9.29 → margin-0.9.30}/margin/observation.py

@@ -18,6 +18,7 @@ from typing import Optional
 
 from .confidence import Confidence
 from .health import Health, Thresholds, classify
+from .issue import Issue, IssueLevel, IssueCode
 
 
 class Absence(Enum):
@@ -240,6 +241,7 @@ class Expression:
     confidence: Confidence = Confidence.MODERATE
     label: str = ""
     step: Optional[int] = None
+    issues: list[Issue] = field(default_factory=list)
 
     def __post_init__(self) -> None:
         if self.observations:
@@ -302,13 +304,16 @@ class Expression:
         return " ".join(parts) if parts else "[∅]"
 
     def to_dict(self) -> dict:
-        return {
+        d = {
             "confidence": self.confidence.value,
             "label": self.label,
             "step": self.step,
             "observations": [o.to_dict() for o in self.observations],
             "corrections": [c.to_dict() for c in self.corrections],
         }
+        if self.issues:
+            d["issues"] = [i.to_dict() for i in self.issues]
+        return d
 
     def to_json(self, indent: int = 2) -> str:
         return json.dumps(self.to_dict(), indent=indent)
@@ -321,6 +326,7 @@ class Expression:
             confidence=Confidence(d["confidence"]) if "confidence" in d else Confidence.MODERATE,
             label=d.get("label", ""),
             step=d.get("step"),
+            issues=[Issue.from_dict(i) for i in d.get("issues", [])],
         )
 
     @classmethod
@@ -416,18 +422,25 @@ class Parser:
         confidences = confidences or {}
         provenance = provenance or []
         absences = absences or {}
+        issues: list[Issue] = []
 
         observations = []
         for name, val in values.items():
             if name in absences:
                 continue  # handled below with the other absences
             if name not in self.baselines:
-                warnings.warn(
-                    f"Parser.parse: component {name!r} has no baseline — "
-                    "using the observed value as baseline (sigma=0). "
-                    "Add it to Parser.baselines or check for a typo.",
-                    stacklevel=2,
+                detail = (
+                    f"component {name!r} has no baseline — using the observed "
+                    "value as baseline (sigma=0). Add it to Parser.baselines "
+                    "or check for a typo."
                 )
+                issues.append(Issue(
+                    level=IssueLevel.WARNING,
+                    code=IssueCode.BASELINE_MISSING,
+                    component=name,
+                    detail=detail,
+                ))
+                warnings.warn(f"Parser.parse: {detail}", stacklevel=2)
             baseline = self.baselines.get(name, val)
             conf = confidences.get(name, Confidence.MODERATE)
             ct = self._thresholds_for(name)
@@ -476,6 +489,7 @@ class Parser:
             observations=observations,
             corrections=corrections,
             confidence=net_conf,
+            issues=issues,
             label=label,
             step=step,
         )