margin 0.8.0__tar.gz → 0.8.2__tar.gz

{margin-0.8.0/margin.egg-info → margin-0.8.2}/PKG-INFO

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

@@ -17,7 +17,10 @@ Structure:
 # Foundation
 from .confidence import Confidence
 from .validity import Validity, ValidityMode
-from .provenance import new_id, are_correlated, merge
+from .provenance import (
+    new_id, _new_id, are_correlated, merge, merge_provenance,
+    ProvenanceNode, ProvenanceGraph, create_root_provenance,
+)
 from .uncertain import UncertainValue, Source, EpistemicSource, UncertaintyMode
 from .algebra import add, subtract, multiply, divide, scale, compare, weighted_average
 from .health import Health, Thresholds, classify, SEVERITY
@@ -112,7 +115,8 @@ __all__ = [
     # Foundation
     "Confidence",
     "Validity", "ValidityMode",
-    "new_id", "are_correlated", "merge",
+    "new_id", "_new_id", "are_correlated", "merge", "merge_provenance",
+    "ProvenanceNode", "ProvenanceGraph", "create_root_provenance",
     "UncertainValue", "Source",
     "add", "subtract", "multiply", "divide", "scale", "compare", "weighted_average",
     "Health", "Thresholds", "classify", "SEVERITY",
@@ -195,4 +199,3 @@ CorrectionRecord = Record
 CorrectionLedger = Ledger
 classify_gap_health = classify
 compare_to_threshold = compare
-merge_provenance = merge

{margin-0.8.0 → margin-0.8.2}/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.0 → margin-0.8.2}/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.0 → margin-0.8.2}/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.2/margin/provenance.py

@@ -0,0 +1,130 @@
+"""
+Provenance tracking for uncertain values.
+Detects correlation between derived values via shared ancestry.
+Optionally tracks full lineage via ProvenanceGraph.
+"""
+
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+def new_id() -> str:
+    """Short unique ID for provenance tracking."""
+    return uuid.uuid4().hex[:8]
+
+# margin-poc compat alias
+_new_id = new_id
+
+
+def are_correlated(ids_a: list[str], ids_b: list[str]) -> bool:
+    """True if two provenance chains share any common ancestor."""
+    return bool(set(ids_a) & set(ids_b))
+
+
+def merge(ids_a: list[str], ids_b: list[str]) -> list[str]:
+    """Merge two provenance chains, adding a new derived ID."""
+    return list(set(ids_a) | set(ids_b) | {new_id()})
+
+# margin-poc compat alias
+merge_provenance = merge
+
+
+# -----------------------------------------------------------------------
+# Provenance graph — full lineage tracking
+# -----------------------------------------------------------------------
+
+@dataclass
+class ProvenanceNode:
+    """
+    A node in the provenance graph representing a single derived value.
+
+    id:         unique identifier
+    operation:  what created this value (e.g. "add", "measure_gap_IOI")
+    source_ids: IDs of input values this was derived from
+    """
+    id: str
+    operation: str
+    source_ids: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict:
+        return {"id": self.id, "operation": self.operation, "source_ids": self.source_ids}
+
+    @classmethod
+    def from_dict(cls, d: dict) -> ProvenanceNode:
+        return cls(id=d["id"], operation=d["operation"], source_ids=d.get("source_ids", []))
+
+
+class ProvenanceGraph:
+    """
+    Tracks the full lineage of uncertain values through computations.
+
+    Used to detect correlations (shared provenance affects how
+    uncertainties combine) and to explain where a value came from.
+    """
+
+    def __init__(self):
+        self.nodes: dict[str, ProvenanceNode] = {}
+
+    def add_node(self, node: ProvenanceNode) -> None:
+        self.nodes[node.id] = node
+
+    def get_node(self, node_id: str) -> Optional[ProvenanceNode]:
+        return self.nodes.get(node_id)
+
+    def find_common_ancestors(self, ids_a: set[str], ids_b: set[str]) -> set[str]:
+        """Find common ancestor IDs between two provenance sets."""
+        return ids_a & ids_b
+
+    def trace_lineage(self, node_id: str, depth: int = 10) -> list[ProvenanceNode]:
+        """Trace the lineage of a node back through the graph (oldest first)."""
+        lineage = []
+        to_visit = [node_id]
+        visited: set[str] = set()
+
+        while to_visit and len(lineage) < depth:
+            current_id = to_visit.pop(0)
+            if current_id in visited:
+                continue
+            visited.add(current_id)
+
+            node = self.get_node(current_id)
+            if node is None:
+                continue
+
+            lineage.append(node)
+            to_visit.extend(node.source_ids)
+
+        return list(reversed(lineage))
+
+    def create_root(self, operation: str = "root") -> str:
+        """Create a root provenance node and return its ID."""
+        node_id = new_id()
+        self.add_node(ProvenanceNode(id=node_id, operation=operation))
+        return node_id
+
+    def derive(self, operation: str, source_ids: list[str]) -> str:
+        """Create a derived provenance node and return its ID."""
+        node_id = new_id()
+        self.add_node(ProvenanceNode(id=node_id, operation=operation, source_ids=source_ids))
+        return node_id
+
+    def to_dict(self) -> dict:
+        return {"nodes": {k: v.to_dict() for k, v in self.nodes.items()}}
+
+    @classmethod
+    def from_dict(cls, d: dict) -> ProvenanceGraph:
+        g = cls()
+        for k, v in d.get("nodes", {}).items():
+            g.add_node(ProvenanceNode.from_dict(v))
+        return g
+
+    def __repr__(self) -> str:
+        return f"ProvenanceGraph({len(self.nodes)} nodes)"
+
+
+def create_root_provenance(operation: str = "root") -> list[str]:
+    """Create a fresh provenance ID for a root (measured) value."""
+    return [new_id()]

{margin-0.8.0 → margin-0.8.2/margin.egg-info}/PKG-INFO

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "margin"
-version = "0.8.0"
+version = "0.8.2"
 description = "Typed health classification, uncertainty algebra, and correction auditing for any system that measures things and needs to explain what happened."
 readme = "README.md"
 license = {text = "MIT"}

margin-0.8.0/margin/provenance.py

@@ -1,21 +0,0 @@
-"""
-Provenance tracking for uncertain values.
-Detects correlation between derived values via shared ancestry.
-"""
-
-import uuid
-
-
-def new_id() -> str:
-    """Short unique ID for provenance tracking."""
-    return uuid.uuid4().hex[:8]
-
-
-def are_correlated(ids_a: list[str], ids_b: list[str]) -> bool:
-    """True if two provenance chains share any common ancestor."""
-    return bool(set(ids_a) & set(ids_b))
-
-
-def merge(ids_a: list[str], ids_b: list[str]) -> list[str]:
-    """Merge two provenance chains, adding a new derived ID."""
-    return list(set(ids_a) | set(ids_b) | {new_id()})