probability-flow 1.4.4__tar.gz → 1.4.5__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (28) hide show
  1. {probability_flow-1.4.4 → probability_flow-1.4.5}/CHANGELOG.md +11 -0
  2. {probability_flow-1.4.4 → probability_flow-1.4.5}/PKG-INFO +1 -1
  3. {probability_flow-1.4.4 → probability_flow-1.4.5}/probability_flow/__init__.py +1 -1
  4. {probability_flow-1.4.4 → probability_flow-1.4.5}/probability_flow/generation.py +309 -23
  5. {probability_flow-1.4.4 → probability_flow-1.4.5}/probability_flow/serialize.py +1 -1
  6. {probability_flow-1.4.4 → probability_flow-1.4.5}/probability_flow/variable.py +42 -0
  7. {probability_flow-1.4.4 → probability_flow-1.4.5}/pyproject.toml +1 -1
  8. {probability_flow-1.4.4 → probability_flow-1.4.5}/.gitignore +0 -0
  9. {probability_flow-1.4.4 → probability_flow-1.4.5}/LICENSE +0 -0
  10. {probability_flow-1.4.4 → probability_flow-1.4.5}/README.md +0 -0
  11. {probability_flow-1.4.4 → probability_flow-1.4.5}/probability_flow/cpd.py +0 -0
  12. {probability_flow-1.4.4 → probability_flow-1.4.5}/probability_flow/decompose.py +0 -0
  13. {probability_flow-1.4.4 → probability_flow-1.4.5}/probability_flow/edges.py +0 -0
  14. {probability_flow-1.4.4 → probability_flow-1.4.5}/probability_flow/eliminate.py +0 -0
  15. {probability_flow-1.4.4 → probability_flow-1.4.5}/probability_flow/engines.py +0 -0
  16. {probability_flow-1.4.4 → probability_flow-1.4.5}/probability_flow/evidence.py +0 -0
  17. {probability_flow-1.4.4 → probability_flow-1.4.5}/probability_flow/factors.py +0 -0
  18. {probability_flow-1.4.4 → probability_flow-1.4.5}/probability_flow/graph.py +0 -0
  19. {probability_flow-1.4.4 → probability_flow-1.4.5}/probability_flow/independent.py +0 -0
  20. {probability_flow-1.4.4 → probability_flow-1.4.5}/probability_flow/inference.py +0 -0
  21. {probability_flow-1.4.4 → probability_flow-1.4.5}/probability_flow/junction.py +0 -0
  22. {probability_flow-1.4.4 → probability_flow-1.4.5}/probability_flow/logical.py +0 -0
  23. {probability_flow-1.4.4 → probability_flow-1.4.5}/probability_flow/noisy.py +0 -0
  24. {probability_flow-1.4.4 → probability_flow-1.4.5}/probability_flow/ordering.py +0 -0
  25. {probability_flow-1.4.4 → probability_flow-1.4.5}/probability_flow/py.typed +0 -0
  26. {probability_flow-1.4.4 → probability_flow-1.4.5}/probability_flow/query.py +0 -0
  27. {probability_flow-1.4.4 → probability_flow-1.4.5}/probability_flow/reveal.py +0 -0
  28. {probability_flow-1.4.4 → probability_flow-1.4.5}/probability_flow/viz.py +0 -0
@@ -1,5 +1,16 @@
1
1
  # Changelog
2
2
 
3
+ ## 1.4.5
4
+
5
+ ### Added
6
+
7
+ - **`variable.gates` and `variable.gate_sources`.** A gate source is a parent,
8
+ so it appears in `parents`, and nothing in that list said which of them were
9
+ there to gate. The only route was `cpd.gates`, which exists on the additive
10
+ family and raises on the other three and on a node with no CPD yet, so
11
+ walking a graph for its gates meant a try/except at every node. Both new
12
+ properties are `()` on anything without gates.
13
+
3
14
  ## 1.4.4
4
15
 
5
16
  ### Added
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: probability-flow
3
- Version: 1.4.4
3
+ Version: 1.4.5
4
4
  Summary: Discrete causal graphs and exact inference.
5
5
  Author-email: Alex Roman <dr.alexroman@gmail.com>
6
6
  License-Expression: MIT
@@ -38,7 +38,7 @@ from .serialize import FORMAT, VERSION, from_json, to_json
38
38
  from .variable import BINARY, Definition, Variable
39
39
  from .viz import render, to_text
40
40
 
41
- __version__ = "1.4.4"
41
+ __version__ = "1.4.5"
42
42
 
43
43
  __all__ = [
44
44
  "__version__",
@@ -19,6 +19,7 @@ is picked, which is why `anchor_rule` is a knob and not a constant.
19
19
 
20
20
  from __future__ import annotations
21
21
 
22
+ import dataclasses
22
23
  import json
23
24
  import math
24
25
  import pathlib
@@ -99,9 +100,25 @@ class GraphSpec:
99
100
  gate_prob: float = 0.0
100
101
  gate_weight_bits_range: tuple[float, float] = (0.0, 1.0)
101
102
 
102
- #: How many nodes a gate's component has, the gate node included. (1, 1)
103
- #: reproduces the old behaviour of a bare gate node with no structure.
104
- gate_size_range: tuple[int, int] = (1, 3)
103
+ # `gate_size_range: tuple[int, int] = (1, 3)` STOOD HERE AND NOTHING READ IT
104
+ # EITHER. Found 2026-10-27 by the dead-knob test written for `max_attempts`,
105
+ # which is the only reason it was found at all -- it had a docstring saying
106
+ # what it would do, so reading the file told you it worked.
107
+ #
108
+ # Unlike `max_attempts`, which is a fossil from the pre-rewrite generator
109
+ # (whose docs specify `for attempt in range(max_attempts)`), THIS ONE IS MINE.
110
+ # It arrived with gating and was never wired. Its claim -- "(1, 1) reproduces
111
+ # the old behaviour of a bare gate node" -- was false in both directions: the
112
+ # default (1, 3) did not grow components either, which is the separate bug
113
+ # where every gate component was exactly 1 node in 556 of 556 graphs.
114
+ #
115
+ # That bug is fixed, but not by this knob: `_grow_structure` now grows gate
116
+ # components inside their structure's size budget. So the DIMENSION is real --
117
+ # Alex specifically asked to see non-trivial gating sub-components -- and it is
118
+ # governed by growth rather than by a range of its own. Deleting the
119
+ # declaration changes no behaviour, because nothing read it. Giving gate
120
+ # components their own size distribution would be a real change to the draw,
121
+ # and so a decision rather than a repair.
105
122
 
106
123
  #: Probability that an UNDETERMINED node with at least two parents is
107
124
  #: definitional. Only the undetermined are rolled: see `_assign_types`.
@@ -161,15 +178,68 @@ class GraphSpec:
161
178
  #: authored demo graph and a bad one for a benchmark item.
162
179
  evidence_observed: object = "world"
163
180
 
164
- #: Virtual evidence, named to match the ordinary-node pair above: the
165
- #: baseline sets the scale (it is P(observation | node false), so the largest
166
- #: reachable LR is 1/baseline), and the weight range sets the log-LR.
181
+ #: Tilt evidence strength by DEPTH from the hypothesis. Alex, 2026-10-23,
182
+ #: naming one of two structures he wants: "a situation where all the
183
+ #: strongest evidence is on the leaves, and they have to get all the way down
184
+ #: to the leaf nodes to reveal it".
185
+ #:
186
+ #: 0.0 flat, every depth drawn alike (the default)
187
+ #: > 0 strongest evidence on the LEAVES
188
+ #: < 0 strongest evidence next to H
189
+ #:
190
+ #: CENTRED, so it redistributes rather than inflates: shallow evidence gets
191
+ #: weaker by as much as deep evidence gets stronger. An uncentred version
192
+ #: raised everything -- shallow went 1.86 to 3.57 bits alongside deep -- which
193
+ #: is a volume knob, not a layout.
194
+ #:
195
+ #: It works through the BASELINE and not only the bits, because the baseline
196
+ #: is what caps strength: p_if cannot exceed 0.99, so the achievable weight is
197
+ #: log2(0.99 / p_if_not). At the shipped ranges 40% of draws are already
198
+ #: clipped by that ceiling, so tilting bits alone would mostly do nothing.
199
+ #:
200
+ #: READ §7.3.3 BEFORE USING IT FOR THE DEBATE SHAPE IT IS NAMED AFTER. It
201
+ #: delivers the layout and NOT the dynamic: influence on H decays about
202
+ #: fivefold per hop, so strong leaf evidence is irrelevant evidence rather
203
+ #: than deferred evidence.
204
+ evidence_depth_tilt: float = 0.0
205
+
206
+ #: Virtual evidence, named to match the ordinary-node pair above. The
207
+ #: baseline is P(observation | node false) and the weight range is the
208
+ #: log-LR, in bits. THE TWO ARE NOT INDEPENDENT: `p_if = baseline * 2**bits`
209
+ #: must stay a probability, so the weight ceiling and the baseline FLOOR
210
+ #: trade against each other (0.02 carries 5.63 bits; 0.001 carries 9.95).
211
+ #: `__post_init__` rejects a pair that cannot both hold rather than quietly
212
+ #: capping the weight, and `_evidence_pair` draws the weight first so this
213
+ #: range is the range you get. See docs/generation.md §7.3.4.
167
214
  evidence_baseline_range: tuple[float, float] = (0.02, 0.35)
168
215
  evidence_weight_bits_range: tuple[float, float] = (0.5, 4.0)
169
- p_evidence_against: float = 0.25 #: P(observing it LOWERS its parent)
216
+ #: How OFTEN evidence lowers its parent, and only that -- opposing evidence
217
+ #: is drawn at the same strength as supporting evidence. It used to be
218
+ #: stronger, because only supporting draws could be clipped (§7.3.4).
219
+ p_evidence_against: float = 0.25
170
220
 
171
221
  hypothesis_name: str = "H"
172
- max_attempts: int = 200
222
+
223
+ # `max_attempts: int = 200` STOOD HERE AND NOTHING EVER READ IT. One
224
+ # occurrence in the module: its own declaration. A documented, settable field
225
+ # that did nothing -- set it to 10,000 or to 1 and the generator behaved
226
+ # identically. Deleted 2026-10-27 rather than wired, and the measurement is
227
+ # why: it looked like the knob you reach for when graphs are being rejected,
228
+ # and after fixing the `AtMost` tautology in `_definitional_cpd` THERE IS NO
229
+ # REJECTION LEFT TO BOUND -- 0 of 300 for the default pool, 0 of 300 with all
230
+ # five logical families, 0 of 300 drawing `AtMost` alone at
231
+ # definitional_prob 0.9, and 0 of 60 in each of 24 grid cells. The entire
232
+ # observed rejection rate, 3 of 24 canonical seeds, was that one bug.
233
+ #
234
+ # Wiring it would also have changed which graph a seed produces, nine days
235
+ # before a freeze, with 4,800 generated graphs whose seeds are their index.
236
+ # Batch-level rejection is already handled: `generate_batch(on_failure=...)`.
237
+ #
238
+ # A control that cannot act is indistinguishable from one that acted and did
239
+ # not help, which is the same family as a check that cannot fail and a gate
240
+ # that cannot pass -- all three turned up in this module within two days. A
241
+ # dead knob that is DOCUMENTED is worse than no knob, because it sends the
242
+ # next person to adjust it instead of reading the error.
173
243
 
174
244
  def __post_init__(self):
175
245
  if self.anchor_rule not in ("uniform", "recent", "degree"):
@@ -224,6 +294,24 @@ class GraphSpec:
224
294
  if sum(self.definition_cpds.values()) <= 0:
225
295
  raise ValueError("definition_cpds weights sum to zero")
226
296
 
297
+ # `p_if = p_if_not * 2**bits` must stay a probability, so the evidence
298
+ # weight range and the evidence baseline range are not independent: the
299
+ # weakest anchor the spec admits has to be able to carry the strongest
300
+ # weight it admits. This used to be enforced by silently capping the
301
+ # weight, which made `evidence_weight_bits_range` a range the generator
302
+ # did not produce. It is a spec error now.
303
+ lo_anchor = self.evidence_baseline_range[0]
304
+ max_bits = self.evidence_weight_bits_range[1]
305
+ reachable = math.log2(0.99 / lo_anchor)
306
+ if max_bits >= reachable:
307
+ raise ValueError(
308
+ f"evidence_weight_bits_range tops out at {max_bits:.2f} bits, but "
309
+ f"an anchor of {lo_anchor:g} can carry at most "
310
+ f"{reachable:.2f} bits (p_if would exceed 0.99). Either lower the "
311
+ f"weight ceiling below {reachable:.2f}, or lower the bottom of "
312
+ f"evidence_baseline_range to {0.99 / 2.0 ** max_bits:.2g} or less."
313
+ )
314
+
227
315
 
228
316
  # --------------------------------------------------------------------------
229
317
  # growth: the topology as plain names, before any probability-flow object
@@ -420,21 +508,51 @@ def _log_uniform_bits(rng, lo, hi, p_negative):
420
508
  return -bits if rng.random() < p_negative else bits
421
509
 
422
510
 
423
- def _evidence_pair(rng, spec):
511
+ def _evidence_pair(rng, spec, depth_fraction=0.0):
424
512
  """`(p_if, p_if_not)` for one virtual-evidence node.
425
513
 
426
- A false-positive anchor plus a log-uniform weight, per Q2. The weight may be
514
+ A log-uniform weight plus a false-positive anchor, per Q2. The weight may be
427
515
  negative, so observing the evidence may LOWER its parent -- a benchmark in
428
516
  which every observation supports its parent is structurally easier than real
429
517
  argument. `p_if_not` is never 0: deterministic virtual evidence is forbidden
430
518
  outright, and an epsilon decorates cleanly where a zero does not.
519
+
520
+ THE WEIGHT IS DRAWN FIRST AND THE ANCHOR SECOND, and that order is the whole
521
+ design. `p_if = p_if_not * 2**bits` has to stay a probability, so the pair is
522
+ constrained: an anchor of 0.35 cannot carry more than log2(0.99/0.35) = 1.5
523
+ bits. Drawing the anchor first and then capping the weight to fit -- which is
524
+ what this did until 2026-10-26 -- silently rewrites the weight, and not
525
+ evenly: it never touches a negative draw (those shrink `p_if`, so they are
526
+ always legal) and it took 1.26 bits off the strongest supporting decile. The
527
+ generator asked for symmetric strength and delivered support 16% weaker than
528
+ opposition, in every graph we had generated.
529
+
530
+ So instead the weight is sovereign and the ANCHOR gives way: it is drawn from
531
+ the part of `evidence_baseline_range` that can carry the weight already
532
+ drawn. Both knobs then mean what they say -- the weight keeps its exact
533
+ stated distribution, the anchor stays inside its stated range -- at the price
534
+ of making the two DEPENDENT: strong evidence gets a low false-positive rate.
535
+ That is not a distortion to apologise for. A low false-positive rate is what
536
+ makes evidence strong; the independent draw was the incoherent version.
537
+
538
+ `GraphSpec.__post_init__` rejects a spec whose ranges cannot be satisfied, so
539
+ there is no silent fallback left here.
431
540
  """
432
- p_if_not = rng.uniform(*spec.evidence_baseline_range)
433
541
  bits = _log_uniform_bits(rng, *spec.evidence_weight_bits_range,
434
542
  p_negative=spec.p_evidence_against)
435
- ceiling = math.log2(0.99 / p_if_not)
436
- p_if = p_if_not * 2.0 ** min(bits, ceiling)
437
- return min(p_if, 0.99), p_if_not
543
+ lo, hi = spec.evidence_baseline_range
544
+ if spec.evidence_depth_tilt:
545
+ # centred on the middle depth, so this redistributes rather than inflates
546
+ offset = 2.0 * spec.evidence_depth_tilt * (depth_fraction - 0.5)
547
+ bits = math.copysign(max(abs(bits) + offset, 0.05), bits)
548
+ # the tilt can ask for more than ANY anchor in range can carry; that is
549
+ # the one place a weight still gives way, and only above the validated
550
+ # ceiling that `evidence_weight_bits_range` alone is held to.
551
+ bits = min(bits, math.log2(0.99 / lo)) if bits > 0 else bits
552
+ if bits > 0.0:
553
+ hi = min(hi, 0.99 / 2.0 ** bits)
554
+ p_if_not = rng.uniform(lo, hi)
555
+ return p_if_not * 2.0 ** bits, p_if_not
438
556
 
439
557
 
440
558
  def _plan_topology(spec, rng):
@@ -539,7 +657,28 @@ def _definitional_cpd(var, rng, spec):
539
657
 
540
658
  if family in _COUNTED:
541
659
  # AtLeast / Exactly / AtMost take a threshold; the others do not.
542
- return family(rng.randint(1, len(over)), over=over, leak=leak)
660
+ #
661
+ # `AtMost`'s TOP VALUE IS A TAUTOLOGY AND MUST NOT BE DRAWN. `AtMost.holds`
662
+ # is `count <= k` and `count` runs 0..len(over), so k == len(over) is
663
+ # unconditionally true: the node stops depending on its constituents and
664
+ # becomes a constant up to its leak. The library refuses to build it --
665
+ # "that is a constant, not a definition" -- so this was not producing bad
666
+ # graphs, it was producing NO graph: 3 of the 24 canonical seeds raised,
667
+ # and all three for exactly this reason.
668
+ #
669
+ # The asymmetry is specific to `AtMost`, so the fix is too. `AtLeast` is
670
+ # meaningful at both ends -- k=1 is `Or`, k=len(over) is `And`. `Exactly`
671
+ # is meaningful at every k. Only an upper bound can be satisfied by
672
+ # everything. A definitional node always has at least two constituents, so
673
+ # `len(over) - 1` is never below 1.
674
+ #
675
+ # P(degenerate) was 1/len(over): 50% at two constituents, 33% at three.
676
+ # Nothing we have generated carries one, because the default pool is
677
+ # (And, Or) and `AtMost` only arrives when a caller passes it explicitly --
678
+ # which is what someone exploring other kinds of argument would do, so it
679
+ # was a trap laid for the next person rather than a live fault.
680
+ top = len(over) - 1 if family is logical.AtMost else len(over)
681
+ return family(rng.randint(1, top), over=over, leak=leak)
543
682
  return family(over=over, leak=leak)
544
683
 
545
684
 
@@ -646,6 +785,76 @@ def _observe_evidence(graph, world, rng, spec):
646
785
  var.observe(rng.random() < float(setting))
647
786
 
648
787
 
788
+ def _spec_fingerprint(spec: GraphSpec) -> dict:
789
+ """The spec as JSON, so the document records what produced it.
790
+
791
+ A SEED WITHOUT A SPEC IS NOT PROVENANCE. The companion docstring below
792
+ explains why the seed needs the generator commit pinned beside it; the same
793
+ argument applies with more force to the spec, which determines far more of
794
+ the graph than the commit does. Found 2026-10-26, going to reproduce
795
+ `lighthouse-142` from its recorded seed 142 and commit bbfa2fb and finding it
796
+ could not be done: nothing anywhere recorded its `GraphSpec`. Of the eight
797
+ graphs this org holds, not one records a spec and five record neither seed nor
798
+ commit, so the frozen benchmark items cannot be regenerated at all.
799
+
800
+ `definition_cpds` holds CLASSES, which do not serialise, so they go in by
801
+ `__name__` -- the same key `__post_init__` sorts on, so a document records the
802
+ draw order it actually used.
803
+ """
804
+ def plain(value):
805
+ if isinstance(value, type):
806
+ return value.__name__
807
+ if isinstance(value, dict):
808
+ return {plain(k): plain(v) for k, v in value.items()}
809
+ if isinstance(value, (list, tuple)):
810
+ return [plain(v) for v in value]
811
+ return value
812
+
813
+ out = {}
814
+ for field in dataclasses.fields(spec):
815
+ value = getattr(spec, field.name)
816
+ if field.name == "structures":
817
+ out[field.name] = [{f.name: getattr(s, f.name)
818
+ for f in dataclasses.fields(s)} for s in value]
819
+ else:
820
+ out[field.name] = plain(value)
821
+ return out
822
+
823
+
824
+ def spec_from_metadata(metadata: dict) -> GraphSpec:
825
+ """Rebuild the `GraphSpec` a document records, so it can be regenerated.
826
+
827
+ The inverse of `_spec_fingerprint`, and the half that makes it provenance
828
+ rather than decoration: `generate(spec_from_metadata(doc["metadata"]),
829
+ seed=doc["metadata"]["seed"])` reproduces the document, given the same
830
+ generator commit. Raises on a document written before specs were recorded,
831
+ because silently substituting the DEFAULT spec there would hand back a
832
+ confident wrong graph -- the pre-2026-10-26 benchmark items are irreproducible
833
+ and should say so rather than look reproducible.
834
+ """
835
+ if "spec" not in metadata:
836
+ raise GenerationError(
837
+ "this document records no spec, so it cannot be reproduced: it "
838
+ "predates spec recording (2026-10-26). Its seed alone does not "
839
+ "determine the graph."
840
+ )
841
+ raw = dict(metadata["spec"])
842
+ raw["structures"] = tuple(StructureSpec(**s) for s in raw["structures"])
843
+ families = {c.__name__: c for c in (logical.And, logical.Or, logical.AtLeast,
844
+ logical.AtMost, logical.Exactly)}
845
+ cpds = raw.get("definition_cpds")
846
+ if isinstance(cpds, dict):
847
+ raw["definition_cpds"] = {families[k]: v for k, v in cpds.items()}
848
+ elif cpds is not None:
849
+ raw["definition_cpds"] = tuple(families[k] for k in cpds)
850
+ for key, value in list(raw.items()):
851
+ if isinstance(value, list) and len(value) == 2 and all(
852
+ isinstance(v, (int, float)) for v in value):
853
+ raw[key] = tuple(value) # JSON has no tuples; ranges are pairs
854
+ known = {f.name for f in dataclasses.fields(GraphSpec)}
855
+ return GraphSpec(**{k: v for k, v in raw.items() if k in known})
856
+
857
+
649
858
  def _generator_fingerprint():
650
859
  """What code made this document, as unambiguously as the install allows.
651
860
 
@@ -661,6 +870,51 @@ def _generator_fingerprint():
661
870
  does, when the package runs from a checkout, so both are recorded and the sha
662
871
  is the one to trust. Finding no sha is normal -- an installed wheel has no
663
872
  repository -- and never interrupts generation.
873
+
874
+ THE SHA IS RECORDED IN FULL, AND WITH THE REMOTE BESIDE IT. A `--short` sha
875
+ was recorded here until 2026-10-26, which is wrong twice over: an abbreviation
876
+ names the object ambiguously, and it names no repository at all -- there are
877
+ two readable `probability-flow` remotes with different tips, so a short sha
878
+ identifies a document's generator only if you already know which one to look
879
+ in. A record whose trustworthy half needs outside context is not provenance.
880
+
881
+ THE DIRTY CHECK ASKS ABOUT THIS FILE BY `__file__`, not by name. It spent its
882
+ whole life asking `git status -- generate.py`, a path that stopped existing
883
+ when the module was renamed to `generation.py`, and git answers a
884
+ non-existent path with empty output -- indistinguishable from a clean tree. So
885
+ the guard against "an uncommitted generator makes the sha a lie" never fired
886
+ once, in the one workspace where seats share a checkout and dirty is the
887
+ normal state. Naming the file by hand is what let it rot; `__file__` cannot.
888
+
889
+ THE QUERY VERIFIES RATHER THAN DISCOVERS, and this is the whole design. GIT
890
+ SEARCHES UPWARD. Installed non-editable, this module lives in
891
+ `site-packages/probability_flow/`, which has no `.git`, so `git -C` there
892
+ walks up until it finds one -- and if the venv sits anywhere inside any
893
+ repository, THAT repository answers. Measured 2026-10-26: a wheel built from
894
+ this project, installed into a venv inside an unrelated repo, produced a
895
+ document claiming that repo's sha and remote. The graph was correct and only
896
+ the provenance lied, which is the worst available combination -- every number
897
+ checks out and the document confidently attributes itself to a repository it
898
+ has never been near.
899
+
900
+ There is no local evidence that distinguishes "the repo I came from" from "a
901
+ repo I happen to sit inside", so discovery cannot be made safe. What CAN be
902
+ established is whether the repository git found actually tracks THIS FILE:
903
+ `git ls-files --error-unmatch` on the module's own path. In the failing case
904
+ it does not -- nothing tracks a path under `site-packages` -- and the whole
905
+ record is then withheld.
906
+
907
+ RECORDING ABSENT IS STRICTLY BETTER THAN RECORDING WRONG. A missing sha says
908
+ "ask someone else", which is what an installed wheel should say; a wrong one
909
+ is believed. The cost is that a venv living INSIDE the real checkout also
910
+ records nothing, because the installed copy under `.venv` is not a tracked
911
+ path either. That is the right trade: it makes an honest gap, not a lie.
912
+
913
+ The remote is deliberately NOT matched against a known URL. There are two
914
+ readable `probability-flow` remotes and forks are legitimate, so a URL
915
+ allow-list would reject real provenance while adding nothing -- the tracked
916
+ path is the structural check, and the remote is recorded as a fact about
917
+ where that verified repo points.
664
918
  """
665
919
  from . import __version__
666
920
 
@@ -668,14 +922,28 @@ def _generator_fingerprint():
668
922
  "generator_version": __version__}
669
923
  try:
670
924
  import subprocess
671
- here = pathlib.Path(__file__).resolve().parent
672
- sha = subprocess.run(["git", "-C", str(here), "rev-parse", "--short", "HEAD"],
673
- capture_output=True, text=True, timeout=5)
925
+
926
+ def git(*args):
927
+ return subprocess.run(["git", "-C", str(here), *args],
928
+ capture_output=True, text=True, timeout=5)
929
+
930
+ module = pathlib.Path(__file__).resolve()
931
+ here = module.parent
932
+
933
+ # VERIFY FIRST: does the repository git finds actually track this file?
934
+ # If not, it is a repo we are merely sitting inside and it knows nothing
935
+ # about this code. Record nothing at all rather than its sha.
936
+ tracked = git("ls-files", "--error-unmatch", "--", str(module))
937
+ if tracked.returncode != 0:
938
+ return fingerprint
939
+
940
+ sha = git("rev-parse", "HEAD")
674
941
  if sha.returncode == 0 and sha.stdout.strip():
675
942
  fingerprint["generator_commit"] = sha.stdout.strip()
676
- dirty = subprocess.run(
677
- ["git", "-C", str(here), "status", "--porcelain", "--", "generate.py"],
678
- capture_output=True, text=True, timeout=5)
943
+ remote = git("remote", "get-url", "origin")
944
+ if remote.returncode == 0 and remote.stdout.strip():
945
+ fingerprint["generator_remote"] = remote.stdout.strip()
946
+ dirty = git("status", "--porcelain", "--", str(module))
679
947
  if dirty.returncode == 0 and dirty.stdout.strip():
680
948
  # an uncommitted generator makes the sha a lie on its own
681
949
  fingerprint["generator_dirty"] = True
@@ -751,11 +1019,28 @@ def generate(spec: GraphSpec | None = None, seed: int = 0) -> CausalGraph:
751
1019
  # fixed: the world is recoverable by whoever still holds the spec.
752
1020
  world = _sample_world(graph, rng)
753
1021
 
1022
+ # Depth from H, for `evidence_depth_tilt`. Undirected, because "how far a
1023
+ # debater must walk to reach it" does not care which way the arrows point.
1024
+ adjacency: dict = {v: set() for v in graph.variables if not isinstance(v, Evidence)}
1025
+ for edge in graph.edges():
1026
+ if edge.source in adjacency and edge.target in adjacency:
1027
+ adjacency[edge.source].add(edge.target)
1028
+ adjacency[edge.target].add(edge.source)
1029
+ hops, frontier = {hypothesis: 0}, [hypothesis]
1030
+ while frontier:
1031
+ here = frontier.pop(0)
1032
+ for neighbour in adjacency[here]:
1033
+ if neighbour not in hops:
1034
+ hops[neighbour] = hops[here] + 1
1035
+ frontier.append(neighbour)
1036
+ deepest = max(hops.values()) or 1
1037
+ depth_fraction = {v: d / deepest for v, d in hops.items()}
1038
+
754
1039
  # virtual evidence on every node EXCEPT the hypothesis -- it is what we infer
755
1040
  for node in list(graph.variables):
756
1041
  if node is hypothesis or isinstance(node, Evidence):
757
1042
  continue
758
- p_if, p_if_not = _evidence_pair(rng, spec)
1043
+ p_if, p_if_not = _evidence_pair(rng, spec, depth_fraction.get(node, 0.0))
759
1044
  # `<claim id>-ve`, so one id convention runs through the whole document
760
1045
  # (Alex, 2026-10-13). The NAME is left as `add_evidence` builds it; only
761
1046
  # the id is in scope here.
@@ -767,7 +1052,8 @@ def generate(spec: GraphSpec | None = None, seed: int = 0) -> CausalGraph:
767
1052
  observation.metadata["cluster"] = node.metadata["cluster"]
768
1053
  _observe_evidence(graph, world, rng, spec)
769
1054
 
770
- graph.metadata.update(seed=seed, **_generator_fingerprint())
1055
+ graph.metadata.update(seed=seed, spec=_spec_fingerprint(spec),
1056
+ **_generator_fingerprint())
771
1057
  check_reveal_legal(graph)
772
1058
  return graph
773
1059
 
@@ -28,7 +28,7 @@ import json
28
28
  from .variable import short
29
29
 
30
30
  FORMAT = "probability-flow/causal-graph"
31
- VERSION = "1.4.4"
31
+ VERSION = "1.4.5"
32
32
 
33
33
  #: Every key a document may carry, at each level. An unknown key is REJECTED.
34
34
  #:
@@ -641,6 +641,48 @@ class Variable:
641
641
  def cpd(self):
642
642
  return self.graph._cpd(self)
643
643
 
644
+ @property
645
+ def gates(self) -> tuple:
646
+ """The gates on this node's CPD, which may be none.
647
+
648
+ ALWAYS A TUPLE, whatever family the node has and even before it has a
649
+ CPD at all. `cpd.gates` exists only on the additive family, so reaching
650
+ through the CPD means a try/except or an isinstance check at every call
651
+ site just to ask whether a node has gates. Walking a graph is the normal
652
+ way to ask, and most nodes you walk past are not additive.
653
+
654
+ Each gate names the `source` that drives it and the parent whose edge it
655
+ `modulates`:
656
+
657
+ [(g.source.id, g.modulates.id) for g in node.gates]
658
+ """
659
+ try:
660
+ cpd = self.cpd
661
+ except KeyError:
662
+ return ()
663
+ return tuple(getattr(cpd, "gates", ()) or ())
664
+
665
+ @property
666
+ def gate_sources(self) -> "tuple[Variable, ...]":
667
+ """The parents of this node that gate, rather than carrying evidence.
668
+
669
+ `parents` cannot answer this and should not try: a gate source IS a
670
+ parent, because the arithmetic needs it to be, so it belongs in that
671
+ list. What was missing is the other half, which is which of them are
672
+ there to gate. The ordinary causal parents are the difference:
673
+
674
+ gating = set(node.gate_sources)
675
+ causal = [p for p in node.parents if p not in gating]
676
+
677
+ A source that drives two gates on the same node appears once.
678
+ """
679
+ seen, out = set(), []
680
+ for gate in self.gates:
681
+ if id(gate.source) not in seen:
682
+ seen.add(id(gate.source))
683
+ out.append(gate.source)
684
+ return tuple(out)
685
+
644
686
  def posterior(self, observations=None, engine=None):
645
687
  """P(this | evidence).
646
688
 
@@ -8,7 +8,7 @@ build-backend = "hatchling.build"
8
8
 
9
9
  [project]
10
10
  name = "probability-flow"
11
- version = "1.4.4"
11
+ version = "1.4.5"
12
12
  description = "Discrete causal graphs and exact inference."
13
13
  readme = "README.md"
14
14
  requires-python = ">=3.11"