probability-flow 1.4.1__tar.gz → 1.4.2__tar.gz

{probability_flow-1.4.1 → probability_flow-1.4.2}/CHANGELOG.md

@@ -1,9 +1,30 @@
 # Changelog
 
-## Unreleased
+## 1.4.2 (2026-10-12)
+
+### Added
+
+- **`edges[].description`**, first-class, mirroring `variables[].description`. It
+  is content about the relation rather than about either end: why this parent
+  bears on this child, how strongly, in words. It crosses into the graph
+  `reveal.induce` builds, while an edge's `metadata` does not, and that split is
+  the reason it is a field rather than a key inside `metadata`: the reveal game
+  strips `metadata` as its ground-truth guard, so decoration kept there is
+  removed exactly when it is wanted.
+- `edges[].metadata`, the private container, completing the bargain the document
+  and variable levels already struck.
 
 ### Fixed
 
+- **An unknown key on an edge was accepted and silently dropped.** The document
+  and each variable were checked against a key set; edges were checked for an
+  unknown `kind` and never for unknown keys, and the writer rebuilt each edge
+  from a three-key literal. So an extra field survived a read, vanished on the
+  next write, and raised nothing. A generator shipping worded edge strengths lost
+  every one of them with no way to tell. Edges are now checked like the other two
+  levels, and an undecorated edge still emits exactly three keys, so existing
+  documents are unchanged.
+
 - **The PyPI page's three sidebar links were dead.** `Homepage`, `Repository` and
   `Issues` all pointed at the source repository, which is private, so every one
   returned a 404 to anyone who found the package and clicked. That shipped with

{probability_flow-1.4.1 → probability_flow-1.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: probability-flow
-Version: 1.4.1
+Version: 1.4.2
 Summary: Discrete causal graphs and exact inference.
 Author-email: Alex Roman <dr.alexroman@gmail.com>
 License-Expression: MIT

{probability_flow-1.4.1 → probability_flow-1.4.2}/probability_flow/__init__.py

@@ -38,7 +38,7 @@ from .serialize import FORMAT, VERSION, from_json, to_json
 from .variable import BINARY, Definition, Variable
 from .viz import render, to_text
 
-__version__ = "1.4.1"
+__version__ = "1.4.2"
 
 __all__ = [
     "__version__",

{probability_flow-1.4.1 → probability_flow-1.4.2}/probability_flow/edges.py

@@ -48,16 +48,31 @@ from __future__ import annotations
 
 
 class Edge:
-    """A directed relation from `source` to `target`."""
+    """A directed relation from `source` to `target`.
+
+    `description` is decorator-written content about the RELATION rather than
+    about either end: why this parent bears on this child, how strongly, in
+    words. It mirrors `Variable.description` and is first-class for a reason that
+    is easy to get backwards. Decoration has to survive into the graph a reader
+    is shown, and the reveal game STRIPS `metadata` as its ground-truth guard,
+    because that is where an implicit prior and a generator's sampled world live.
+    So text put in `metadata` would be removed exactly when it is wanted, and
+    text put here is carried across.
+
+    `metadata` is the private container, ignored by this library and round-tripped
+    verbatim, the same bargain it strikes at the document and variable levels.
+    """
 
-    __slots__ = ("source", "target")
+    __slots__ = ("source", "target", "description", "metadata")
 
     #: Shown in errors and renderings; subclasses override.
     kind = "edge"
 
-    def __init__(self, source, target):
+    def __init__(self, source, target, description=None):
         self.source = source
         self.target = target
+        self.description = description
+        self.metadata = {}
 
     @property
     def endpoints(self):

{probability_flow-1.4.1 → probability_flow-1.4.2}/probability_flow/reveal.py

@@ -138,7 +138,9 @@ def induce(graph, revealed):
     METADATA IS NOT COPIED, and that is a guard rather than an omission.
     `metadata` is where `q` lives and also where a generator records what it
     knows, so copying it would leak ground truth into the very artifact the judge
-    reasons over.
+    reasons over. An EDGE'S `description` IS copied, and the two facts are one
+    decision: decoration a reader is meant to see has to be first-class, because
+    anything kept in `metadata` is removed exactly when it is wanted.
 
     DEPTH ONE. An unrevealed parent contributes its `q` and nothing else -- no
     CPD, no parents of its own, no virtual evidence. Walking further up is the
@@ -193,7 +195,14 @@ def induce(graph, revealed):
     # claim a node that is not there.
     for e in graph.edges():
         if id(e.source) in revealed_ids and id(e.target) in revealed_ids:
-            out.add_edge(mirror[id(e.source)], mirror[id(e.target)], type(e))
+            drawn = out.add_edge(mirror[id(e.source)], mirror[id(e.target)], type(e))
+            # THE DESCRIPTION CROSSES AND THE METADATA DOES NOT, and that split is
+            # the whole reason an edge's description is first-class rather than a
+            # key inside `metadata`. The text is what a reader is MEANT to see;
+            # `metadata` is where an implicit prior and a generator's sampled
+            # world live, so it is stripped. Decoration kept in `metadata` would
+            # be removed exactly when it was wanted.
+            drawn.description = e.description
 
     # The CPDs, after the edges, because a CPD is validated against its node's
     # parents and they have to exist first.
@@ -217,7 +226,8 @@ def induce(graph, revealed):
         copy = Evidence(mirror[id(v)], ev.label, ev.name, states=ev.states,
                         id=ev.id, description=ev.description)
         out._insert(copy)
-        out.add_edge(mirror[id(v)], copy, type(graph.edge(v, ev)))
+        rider = out.add_edge(mirror[id(v)], copy, type(graph.edge(v, ev)))
+        rider.description = graph.edge(v, ev).description
         out._cpds[id(copy)] = graph._cpd(ev).partially_revealed(
             [mirror[id(v)]], unrevealed_q={}, child=copy)
         mirror[id(ev)] = copy

{probability_flow-1.4.1 → probability_flow-1.4.2}/probability_flow/serialize.py

@@ -28,7 +28,7 @@ import json
 from .variable import short
 
 FORMAT = "probability-flow/causal-graph"
-VERSION = "1.4.1"
+VERSION = "1.4.2"
 
 #: Every key a document may carry, at each level. An unknown key is REJECTED.
 #:
@@ -39,9 +39,17 @@ VERSION = "1.4.1"
 #: producer's output surfaces on the first read instead of silently dropping
 #: whatever it was meant to say.
 #:
-#: `metadata` is the single exception, at both levels: an explicit container
-#: whose contents this library never inspects. Everything else strict, one place
-#: to extend.
+#: `metadata` is the single exception, at ALL THREE levels: the document, a
+#: variable and an edge. An explicit container whose contents this library never
+#: inspects. Everything else strict, one place to extend.
+#:
+#: THERE WERE ONLY TWO LEVELS HERE UNTIL AN EDGE ATE A COLLABORATOR'S WORK. Edges
+#: were checked for an unknown KIND and never for unknown KEYS, and the writer
+#: rebuilt each one from a three-key literal, so an extra key was accepted on read
+#: and dropped on write with nothing raised. A generator shipping worded edge
+#: strengths lost every one of them silently. The comment above this one used to
+#: say "at both levels" and meant the document and a variable, which named the
+#: missing third level without noticing it.
 TOP_LEVEL_KEYS = frozenset({
     "format", "version", "name", "hypothesis", "produced_by", "metadata",
     "engine_config", "variables", "edges", "cpds",
@@ -50,6 +58,9 @@ VARIABLE_KEYS = frozenset({
     "id", "name", "states", "description", "observed", "definitional",
     "evidence_for", "label", "metadata",
 })
+EDGE_KEYS = frozenset({
+    "source", "target", "kind", "description", "metadata",
+})
 
 
 #: Engine settings this version knows how to validate. Unknown keys inside
@@ -133,6 +144,17 @@ def _validate_engine_config(config) -> None:
             )
 
 
+def _decorate(edge, spec) -> None:
+    """Carry an edge's decoration off its document spec.
+
+    One function for both routes, because there are two: an ordinary edge is
+    created here, and an edge into a virtual-evidence node was already created by
+    `add_evidence`. Those were decorated in two places until one of them was not.
+    """
+    edge.description = spec.get("description")
+    edge.metadata = _copy(spec.get("metadata", {}))
+
+
 def _reject_unknown(spec, known, where) -> None:
     unknown = sorted(set(spec) - known)
     if unknown:
@@ -349,7 +371,11 @@ def to_json(graph, *, indent: int = 2) -> str:
         "variables": variables,
         "edges": [
             {"source": node_ref(e.source), "target": node_ref(e.target),
-             "kind": e.kind}
+             "kind": e.kind,
+             # Omitted when empty, so an undecorated edge still emits the same
+             # three keys it always did and existing documents are unchanged.
+             **({"description": e.description} if e.description else {}),
+             **({"metadata": _copy(e.metadata)} if e.metadata else {})}
             for e in _canonical_edges(graph)
         ],
         "cpds": [
@@ -448,6 +474,10 @@ def from_json(text: str):
     # variables. Definition-ness is derived from the edges, so the edge list
     # has to be consulted before any node is created.
     edge_specs = doc.get("edges", [])
+    for i, spec in enumerate(edge_specs):
+        _reject_unknown(spec, EDGE_KEYS,
+                        f"edge {spec.get('source')!r} -> {spec.get('target')!r}"
+                        if isinstance(spec, dict) else f"edge at index {i}")
     definitional = {
         e["target"] for e in edge_specs if e.get("kind") == "constitutive"
     }
@@ -546,8 +576,14 @@ def from_json(text: str):
                     f"two edges both say {e['source']!r} -> {e['target']!r}"
                 )
             seen_into_evidence.add(tgt.id)
+            # THE EDGE ALREADY EXISTS: `add_evidence` drew it in the pass above,
+            # so this one is not created here and used to `continue` before any
+            # decoration was read. On the file this was first tested against,
+            # that lost 19 of 43 edge descriptions, one per evidence channel,
+            # and lost them silently because the other 24 came through.
+            _decorate(g.edge(src, tgt), e)
             continue
-        g.add_edge(src, tgt, kinds[kind])
+        _decorate(g.add_edge(src, tgt, kinds[kind]), e)
 
     # Restore the document's own variable order. Evidence nodes go through
     # add_evidence in a second pass, so they arrive last no matter where the

{probability_flow-1.4.1 → probability_flow-1.4.2}/pyproject.toml

@@ -8,7 +8,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "probability-flow"
-version = "1.4.1"
+version = "1.4.2"
 description = "Discrete causal graphs and exact inference."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -70,6 +70,16 @@ include = ["/probability_flow", "/README.md", "/CHANGELOG.md", "/LICENSE",
 [tool.pytest.ini_options]
 pythonpath = ["."]
 testpaths = ["tests"]
+# `release` is DESELECTED BY DEFAULT, and that is the point rather than a
+# convenience. A check that the tag matches HEAD is true only at the moment of
+# release: between tagging and uploading, every ordinary commit moves HEAD past
+# the tag, so running it in the normal suite would force a version bump for each
+# commit, and a version bump regenerates every shipped document. It would have
+# made the repository unworkable for exactly the window it was written to protect.
+addopts = "-m 'not release'"
+markers = [
+    "release: run at release time only. `uv run pytest -m release` is the gate.",
+]
 
 [tool.ruff]
 line-length = 100