probability-flow 0.2.0__tar.gz → 0.3.0__tar.gz

{probability_flow-0.2.0 → probability_flow-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: probability-flow
-Version: 0.2.0
+Version: 0.3.0
 Summary: A from-scratch, modular discrete Bayesian-network library.
 Project-URL: Homepage, https://github.com/scalable-oversight-benchmarks/probability-flow
 Project-URL: Repository, https://github.com/scalable-oversight-benchmarks/probability-flow
@@ -118,6 +118,13 @@ combiner) from the *object* that implements it (the CPD).
   sources of evidence: `logit P(node=1) = logit(prior) + sum of log(lr)` over the
   active inputs. Adding weights of evidence is Bayes' rule for independent
   likelihood ratios. Set per edge with `add_input(x, lr=...)`.
+- **CorrelatedEvidenceCPD**. Independent evidence plus pairwise couplings, for
+  *redundant* inputs the additive rule would otherwise double-count (two reports of
+  one fact, two clues from a shared cause): it adds a pairwise term
+  `+ sum J_ij s_i s_j` (a negative `J` makes two inputs sub-additive when both fire,
+  a positive one synergistic). The coupling lives inside the single CPD factor, so
+  it adds no edge to the graph and no loop to the solver, and stays a valid
+  distribution for any real `J`.
 - **NoisyOrCPD**. "Any one cause can fire the effect":
   `P(node=0) = (1 - leak) * product of (1 - activation)` over present causes.
   Declared with `node.noisy_or(leak=...)` and `add_input(cause, activation=...)`.

{probability_flow-0.2.0 → probability_flow-0.3.0}/README.md

@@ -84,6 +84,13 @@ combiner) from the *object* that implements it (the CPD).
   sources of evidence: `logit P(node=1) = logit(prior) + sum of log(lr)` over the
   active inputs. Adding weights of evidence is Bayes' rule for independent
   likelihood ratios. Set per edge with `add_input(x, lr=...)`.
+- **CorrelatedEvidenceCPD**. Independent evidence plus pairwise couplings, for
+  *redundant* inputs the additive rule would otherwise double-count (two reports of
+  one fact, two clues from a shared cause): it adds a pairwise term
+  `+ sum J_ij s_i s_j` (a negative `J` makes two inputs sub-additive when both fire,
+  a positive one synergistic). The coupling lives inside the single CPD factor, so
+  it adds no edge to the graph and no loop to the solver, and stays a valid
+  distribution for any real `J`.
 - **NoisyOrCPD**. "Any one cause can fire the effect":
   `P(node=0) = (1 - leak) * product of (1 - activation)` over present causes.
   Declared with `node.noisy_or(leak=...)` and `add_input(cause, activation=...)`.

{probability_flow-0.2.0 → probability_flow-0.3.0}/probability_flow/__init__.py

@@ -12,12 +12,14 @@ from .core import (
     CPD,
     BayesianNetwork,
     CompiledCPD,
+    CorrelatedEvidenceCPD,
     ExactSolver,
     IndependentEvidenceCPD,
     LoopySolver,
     Node,
     NoisyAndCPD,
     NoisyOrCPD,
+    PendingWeightError,
     TabularCPD,
 )
 
@@ -36,6 +38,8 @@ __all__ = [
     "CPD",
     "TabularCPD",
     "IndependentEvidenceCPD",
+    "CorrelatedEvidenceCPD",
     "NoisyOrCPD",
     "NoisyAndCPD",
+    "PendingWeightError",
 ]

{probability_flow-0.2.0 → probability_flow-0.3.0}/probability_flow/aspic/argument.py

@@ -41,9 +41,12 @@ class _Claim(Node):
 
     def __init__(self, name: str, prior: float = 0.5):
         super().__init__(name, prior=prior)
-        self._edges: list[tuple["Node", float, str]] = []  # (src, lr, kind)
+        self._edges: list[tuple["Node", "float | None", str]] = []  # (src, lr, kind)
         self._strict: list["Node"] = []                    # strict sources
         self._undercuts: list[tuple["Node", "Node"]] = []  # (attacked source, undercutter)
+        # (source_a, source_b, J): residual correlation between two defeasible
+        # sources of this conclusion, lowered to a CorrelatedEvidenceCPD coupling.
+        self._correlations: list[tuple["Node", "Node", "float | None"]] = []
         self._no_undermine = False
         # opaque, serialized but uninterpreted by the library (see docs/aspic.md):
         self.desc: str | None = None              # a longer description
@@ -63,21 +66,24 @@ class _Claim(Node):
 
     # --- defeasible and strict support (methods on the downstream conclusion) --
 
-    def support(self, src: "Node", lr: float) -> "Node":
+    def support(self, src: "Node", lr: "float | None" = None) -> "Node":
         """Add a defeasible argument *for* this conclusion (`lr > 1`). Returns
         `src`, so an inline source can be built further upstream, as with core
-        `add_input`."""
-        if not lr > 1:
+        `add_input`. `lr` may be omitted (`None`) to declare the edge before its
+        strength is known — the topology compiles and renders (dashed), but the
+        network cannot be solved until every weight is assigned."""
+        if lr is not None and not lr > 1:
             raise ValueError(
                 f"support lr must be > 1 (got {lr}); use rebut for an argument against"
             )
         self._require_new_edge(src)
-        self._edges.append((src, float(lr), "support"))
+        self._edges.append((src, None if lr is None else float(lr), "support"))
         return src
 
-    def rebut(self, src: "Node", lr: float) -> "Node":
-        """Add a defeasible argument *against* this conclusion (`0 < lr < 1`)."""
-        if not 0 < lr < 1:
+    def rebut(self, src: "Node", lr: "float | None" = None) -> "Node":
+        """Add a defeasible argument *against* this conclusion (`0 < lr < 1`). `lr`
+        may be omitted (`None`) to declare the edge before its strength is known."""
+        if lr is not None and not 0 < lr < 1:
             raise ValueError(
                 f"rebut lr must be in (0, 1) (got {lr}); use support for an argument for"
             )
@@ -89,7 +95,7 @@ class _Claim(Node):
                 stacklevel=2,
             )
         self._require_new_edge(src)
-        self._edges.append((src, float(lr), "rebut"))
+        self._edges.append((src, None if lr is None else float(lr), "rebut"))
         return src
 
     def strict(self, src: "Node") -> "Node":
@@ -101,18 +107,19 @@ class _Claim(Node):
 
     # --- attacks (also methods on the downstream node) ------------------------
 
-    def undermine(self, by: "Node", lr: float) -> "Node":
+    def undermine(self, by: "Node", lr: "float | None" = None) -> "Node":
         """Attack this premise with `by` (`0 < lr < 1`). Mechanically a rebut into
         the attacked node, named distinctly because it is the ASPIC-correct verb
-        for attacking a premise. An axiom cannot be undermined."""
+        for attacking a premise. An axiom cannot be undermined. `lr` may be omitted
+        (`None`) to declare the edge before its strength is known."""
         if self._no_undermine:
             raise ValueError(
                 f"cannot undermine {self.name!r}: an axiom has no defeasible premise to attack"
             )
-        if not 0 < lr < 1:
+        if lr is not None and not 0 < lr < 1:
             raise ValueError(f"undermine lr must be in (0, 1) (got {lr})")
         self._require_new_edge(by)
-        self._edges.append((by, float(lr), "undermine"))
+        self._edges.append((by, None if lr is None else float(lr), "undermine"))
         return by
 
     def undercut(self, source: "Node", by: "Node") -> "Node":
@@ -123,6 +130,39 @@ class _Claim(Node):
         self._undercuts.append((source, by))
         return by
 
+    def correlate(self, source_a: "Node", source_b: "Node",
+                  coupling: "float | None" = None) -> "_Claim":
+        """Declare residual correlation between two **defeasible sources** of this
+        conclusion — redundancy (two reports of one fact, a shared cause) or
+        synergy. Lowered to a pairwise `CorrelatedEvidenceCPD` coupling `J`:
+        negative discounts the pair (redundant / sub-additive), positive boosts it.
+        `J` is the engine-native quantity (a caller with a correlation or a pair of
+        conditional probabilities does the inverse map). `coupling` may be omitted
+        to scaffold the pair before its value is chosen. Returns self for chaining.
+
+        This overrides the core `Node.correlate`: a `_Claim` declares the pairing
+        against its argument sources here, and `compile` lowers it onto whichever
+        core node carries the defeasible inputs.
+        """
+        sources = {id(s) for s, _lr, kind in self._edges if kind in ("support", "rebut")}
+        for x in (source_a, source_b):
+            if id(x) not in sources:
+                raise ValueError(
+                    f"{getattr(x, 'name', x)!r} is not a support/rebut source of "
+                    f"{self.name!r}; correlate couples two of its defeasible sources"
+                )
+        if source_a is source_b:
+            raise ValueError("cannot correlate a source with itself")
+        if any({id(source_a), id(source_b)} == {id(a), id(b)}
+               for a, b, _J in self._correlations):
+            raise ValueError(
+                f"{source_a.name!r} and {source_b.name!r} are already correlated on "
+                f"{self.name!r}"
+            )
+        self._correlations.append(
+            (source_a, source_b, None if coupling is None else float(coupling)))
+        return self
+
     def compile(self) -> "BayesianNetwork":
         """Lower this argument (as the target) to a core `BayesianNetwork`."""
         from .compile import compile_argument

{probability_flow-0.2.0 → probability_flow-0.3.0}/probability_flow/aspic/compile.py

@@ -166,6 +166,7 @@ def _lower(c: "_Claim") -> None:
         d = Node(f"{c.name}/defeasible", prior=c.prior)
         for src, lr in defeasible:
             d.add_input(src, lr=lr)
+        _apply_correlations(c, d, resolve)
         c.noisy_or(leak=0.0)
         for src in strict:
             c.add_input(src, activation=1.0)
@@ -173,3 +174,14 @@ def _lower(c: "_Claim") -> None:
     else:
         for src, lr in defeasible:
             c.add_input(src, lr=lr)
+        _apply_correlations(c, c, resolve)
+
+
+def _apply_correlations(c: "_Claim", host: "Node", resolve) -> None:
+    """Lower `c`'s declared source correlations onto `host` — the core node that
+    actually carries the defeasible inputs (the conclusion itself, or its hidden
+    `/defeasible` node when strict edges divorced it). Uses `Node.correlate`
+    explicitly: `c` overrides `correlate` with the argument-level declaration, so
+    the core coupling must be reached through the base class."""
+    for a, b, coupling in getattr(c, "_correlations", []):
+        Node.correlate(host, resolve(a), resolve(b), coupling=coupling)

{probability_flow-0.2.0 → probability_flow-0.3.0}/probability_flow/aspic/handle.py

@@ -30,7 +30,7 @@ if TYPE_CHECKING:
     from ..core import BayesianNetwork, Node
     from .argument import _Claim
 
-SCHEMA_VERSION = "0.1"
+SCHEMA_VERSION = "0.2"   # 0.2 adds the optional `correlations` array
 
 # Above this many nodes the brute-force ExactSolver fallback (2**n joint
 # enumeration, used only on non-polytree arguments) gets painfully slow. See the
@@ -154,7 +154,10 @@ class Argument:
         from .argument import Axiom, Premise, _Claim
 
         bn = self.bn
-        solver = self.solver
+        # a pending argument (some edge weight unassigned) cannot be solved, so the
+        # posterior fields serialize as null; the topology round-trips regardless.
+        complete = bn.is_complete
+        solver = self.solver if complete else None
         claims = [c for c in _reachable(self.target) if isinstance(c, _Claim)]
         non_claim = [c for c in _reachable(self.target) if not isinstance(c, _Claim)]
         if non_claim:
@@ -178,16 +181,16 @@ class Argument:
             return name[:-3] if name.endswith("CPD") else name
 
         def node_dict(c: "_Claim") -> dict:
-            lo, hi = self.posterior_range(c)
+            lo, hi = self.posterior_range(c) if complete else (None, None)
             return {
                 "id": ids[c],
                 "type": type_of(c),
                 "label": c.name,
                 "desc": c.desc,
                 "prior": float(c.prior),
-                "posterior": float(solver.prob(c, 1)),
-                "min_posterior": float(lo),
-                "max_posterior": float(hi),
+                "posterior": float(solver.prob(c, 1)) if solver else None,
+                "min_posterior": None if lo is None else float(lo),
+                "max_posterior": None if hi is None else float(hi),
                 "input_groups_sizes": self.input_groups_sizes(c),
                 "cpd_type": cpd_type(c),
                 "revealable_to_judge": c.revealable_to_judge,
@@ -220,8 +223,19 @@ class Argument:
             for src in c._strict:
                 edges.append(edge(src, "strict", None))
 
+        # residual correlations between two defeasible sources of a conclusion
+        # (lowered to CorrelatedEvidenceCPD couplings); not source->target edges.
+        correlations = []
+        for c in claims:
+            for a, b, coupling in getattr(c, "_correlations", []):
+                correlations.append({
+                    "target": ids[c],
+                    "sources": [ids[a], ids[b]],
+                    "coupling": None if coupling is None else float(coupling),
+                })
+
         return {"version": SCHEMA_VERSION, "target": ids[self.target],
-                "nodes": nodes, "edges": edges}
+                "nodes": nodes, "edges": edges, "correlations": correlations}
 
     def to_json(self, *, indent: int = 2) -> str:
         return json.dumps(self.to_dict(), indent=indent)
@@ -267,15 +281,26 @@ class Argument:
                 edge_meta[ed["id"]] = {"label": ed.get("label"),
                                        "revealable_to_judge": ed.get("revealable_to_judge")}
 
+        for cor in data.get("correlations", []):
+            a, b = cor["sources"]
+            by_id[cor["target"]].correlate(
+                by_id[a], by_id[b], coupling=cor.get("coupling"))
+
         arg = cls(by_id[data["target"]])
         arg._edge_meta = edge_meta
         return arg
 
     @classmethod
-    def from_json(cls, s: str) -> "Argument":
-        return cls.from_dict(json.loads(s))
+    def from_json(cls, s: str, *, source: str = "<string>") -> "Argument":
+        if not s.strip():
+            raise ValueError(f"cannot load an Argument from empty JSON ({source})")
+        try:
+            data = json.loads(s)
+        except json.JSONDecodeError as exc:
+            raise ValueError(f"{source} is not valid JSON: {exc}") from exc
+        return cls.from_dict(data)
 
     @classmethod
     def load(cls, path: str) -> "Argument":
         with open(path) as f:
-            return cls.from_json(f.read())
+            return cls.from_json(f.read(), source=path)

{probability_flow-0.2.0 → probability_flow-0.3.0}/probability_flow/aspic/visualization.py

@@ -10,7 +10,12 @@ from __future__ import annotations
 from typing import Mapping, Optional
 
 from ..visualization import draw_layered, marginals
-from ..visualization.image import _lr_colormap, _require_matplotlib, lr_colorbar_spec
+from ..visualization.image import (
+    _NEUTRAL_EDGE,
+    _lr_colormap,
+    _require_matplotlib,
+    lr_colorbar_spec,
+)
 from ..visualization.style import fmt
 from .argument import Axiom, Premise, _Claim
 from .compile import _reachable
@@ -21,6 +26,7 @@ _AXIOM = "#ffe6a8"
 _CONCLUSION = "#ffffff"
 _STRICT = {"color": "#222222", "style": "-", "width": 2.6}    # bold black (forcing)
 _UNDERCUT = {"color": "#7d3c98", "style": ":", "width": 1.6}  # purple, attacks an edge
+_CORRELATION = "#2a9d8f"   # teal, undirected dashed: residual correlation between sources
 _CONFIRMING = "#3b4cc0"     # coolwarm_r extremes, for the legend swatches
 _DISCONFIRMING = "#b40426"
 
@@ -64,8 +70,12 @@ def render_argument(
         # support/rebut/undermine coloured by LR; strict bold black. Emit each edge
         # then its undercutters, so the layout puts an undercutter beside the source
         # it attacks (v=c only sets the layout; the arrow lands on the source->c edge).
-        rows = [(src, {"u": src, "v": c, "label": f"lr={fmt(lr)}",
-                       "color": color_for_lr(lr), "style": "-", "width": 2.0})
+        # a defeasible edge whose lr is not yet assigned draws dashed and grey with
+        # no label ("edge exists, strength TBD"); an assigned one is coloured by lr.
+        rows = [(src, {"u": src, "v": c, "label": "" if lr is None else f"lr={fmt(lr)}",
+                       "color": _NEUTRAL_EDGE if lr is None else color_for_lr(lr),
+                       "style": "--" if lr is None else "-",
+                       "width": 1.4 if lr is None else 2.0})
                 for src, lr, _kind in c._edges]
         rows += [(s, {"u": s, "v": c, "label": "strict", **_STRICT}) for s in c._strict]
 
@@ -82,6 +92,12 @@ def render_argument(
                 for by in bys:
                     edges.append({"u": by, "v": c, "attacks": (source, c), **_UNDERCUT})
 
+        # residual correlation between two sources: an undirected dashed coupling.
+        for a, b, coupling in getattr(c, "_correlations", []):
+            edges.append({"u": a, "v": b, "arrow": False, "style": "--",
+                          "color": _CORRELATION, "width": 1.3,
+                          "label": "" if coupling is None else f"J={fmt(coupling)}"})
+
     if values is None and beliefs:
         m = marginals(target.compile(), evidence)
         values = {c: m[c] for c in claims if c in m}
@@ -106,6 +122,7 @@ def render_argument(
         color_of=color_of, label_of=label_of, font=_ARG_FONT,
         ax=ax, title=title, path=path, emphasize=set(evidence or {}),
         positions=positions, orientation=orientation,
+        center=(0.0, 0.0) if layout == "radial" else None,
         colorbar=lr_colorbar_spec(all_lrs) if colorbar else None,
         legend=_argument_legend(claims) if legend else None,
     )
@@ -122,13 +139,17 @@ def _argument_legend(claims) -> list:
         node_row.append(("conclusion", {"marker": "o", "fill": _CONCLUSION}))
 
     edge_row = []
-    lrs = [lr for c in claims for _src, lr, _kind in c._edges]
+    lrs = [lr for c in claims for _src, lr, _kind in c._edges if lr is not None]
     if any(lr > 1 for lr in lrs):
         edge_row.append(("confirming", {"color": _CONFIRMING, "linestyle": "-"}))
     if any(lr < 1 for lr in lrs):
         edge_row.append(("disconfirming", {"color": _DISCONFIRMING, "linestyle": "-"}))
+    if any(lr is None for c in claims for _src, lr, _kind in c._edges):
+        edge_row.append(("unassigned", {"color": _NEUTRAL_EDGE, "linestyle": "--"}))
     if any(c._strict for c in claims):
         edge_row.append(("strict", {"color": _STRICT["color"], "linestyle": "-"}))
     if any(c._undercuts for c in claims):
         edge_row.append(("undercut", {"color": _UNDERCUT["color"], "linestyle": ":"}))
+    if any(getattr(c, "_correlations", None) for c in claims):
+        edge_row.append(("correlation", {"color": _CORRELATION, "linestyle": "--"}))
     return [r for r in (node_row, edge_row) if r]

{probability_flow-0.2.0 → probability_flow-0.3.0}/probability_flow/core/__init__.py

@@ -6,9 +6,11 @@ and query with the `ExactSolver` (later: loopy BP).
 from .bp import LoopySolver
 from .cpd import (
     CPD,
+    CorrelatedEvidenceCPD,
     IndependentEvidenceCPD,
     NoisyAndCPD,
     NoisyOrCPD,
+    PendingWeightError,
     TabularCPD,
 )
 from .exact import ExactSolver
@@ -24,6 +26,8 @@ __all__ = [
     "CPD",
     "TabularCPD",
     "IndependentEvidenceCPD",
+    "CorrelatedEvidenceCPD",
     "NoisyOrCPD",
     "NoisyAndCPD",
+    "PendingWeightError",
 ]

{probability_flow-0.2.0 → probability_flow-0.3.0}/probability_flow/core/bp/engine.py

@@ -47,6 +47,7 @@ class LoopySolver:
     ):
         if not 0.0 <= damping < 1.0:
             raise ValueError("damping must be in [0, 1)")
+        network.require_complete()
         self.network = network
         self.max_iters = max_iters
         self.tol = tol

{probability_flow-0.2.0 → probability_flow-0.3.0}/probability_flow/core/cpd/__init__.py

@@ -1,4 +1,5 @@
-from .base import CPD
+from .base import CPD, PendingWeightError
+from .correlated_evidence import CorrelatedEvidenceCPD
 from .independent_evidence import IndependentEvidenceCPD
 from .noisy_and import NoisyAndCPD
 from .noisy_or import NoisyOrCPD
@@ -6,7 +7,9 @@ from .tabular import TabularCPD
 
 __all__ = [
     "CPD",
+    "PendingWeightError",
     "IndependentEvidenceCPD",
+    "CorrelatedEvidenceCPD",
     "NoisyAndCPD",
     "NoisyOrCPD",
     "TabularCPD",

{probability_flow-0.2.0 → probability_flow-0.3.0}/probability_flow/core/cpd/base.py

@@ -22,6 +22,14 @@ if TYPE_CHECKING:
     from .tabular import TabularCPD
 
 
+class PendingWeightError(ValueError):
+    """An edge exists but its weight (an LR, or a noisy activation) is not yet
+    assigned, so the CPD cannot be made into a probability table. Subclasses
+    `ValueError` so existing handlers still catch it; raised distinctly so
+    `BayesianNetwork.from_nodes` can tell a *pending* network (one still being
+    authored — topology drawn, weights TBD) from a genuinely malformed one."""
+
+
 class CPD(ABC):
     node: "Node"  # the node this CPD is for