probability-flow 0.1.0__py3-none-any.whl

probability_flow/aspic/generate.py

@@ -0,0 +1,397 @@
+"""Random ASPIC argument-graph generator. See docs/generation.md.
+
+Builds typed arguments *directly* — `Premise` / `Axiom` / `Conclusion` wired with
+`support` / `rebut` / `strict` / `undermine` / `undercut` — and returns an
+`Argument`, then screens by difficulty through the metrics seam. There is no
+post-hoc type relabelling and no `LR == 9999` sentinel: the type is chosen as each
+node is made.
+
+Structural model: a root fed by `n_support` supporting and `n_attack` attacking
+branches. In the default no-share mode every branch is built from fresh nodes, so
+the branches are mutually d-separated and `n_groups` (= `n_support + n_attack`) is
+the *exact* d-separated-group count. A branch is a **tree** (a conclusion can draw
+several sub-arguments — fan-in — not just a chain); a sub-argument can support or
+*attack* its parent conclusion (`internal_attack_prob`), so attack-of-an-attack
+falls out; undercutters and underminers can themselves be small sub-arguments
+(`attacker_depth_range`); a strict internal edge compiles to a noisy-OR. Everything
+stays a polytree (fresh disjoint nodes), so the d-sep dial holds and loopy BP is
+exact.
+
+`generate(...)` wraps the builder in a rejection loop (the hybrid strategy:
+rejection now, a constructive pass for hard targets later). It calibrates the root
+prior to a *target posterior value* by bisection, grows to a target claim count
+constructively, and screens realized depth. The branch-level methods
+(`add_support_branch` / `add_attack_branch`) are usable directly to hand-script a
+template.
+"""
+from __future__ import annotations
+
+import math
+import random
+from dataclasses import dataclass
+from typing import Optional
+
+from .argument import Axiom, Conclusion, Premise, _Claim
+from .compile import _reachable
+from .handle import Argument
+
+
+@dataclass
+class StructuralParams:
+    """Knobs the proposer draws from (the *shape*, not the difficulty target). The
+    number of d-separated groups is `n_support + n_attack`, set explicitly."""
+
+    n_support: int = 2                       # supporting branches into the root
+    n_attack: int = 1                        # attacking branches into the root
+    min_depth: int = 1                       # per-branch chain length, drawn uniform
+    max_depth: int = 3
+    depths: Optional[list] = None            # exact per-branch depths (len == n_groups)
+    max_fanin: int = 2                       # extra sub-arguments per conclusion
+    fanin_prob: float = 0.3                  # probability of each extra sub-argument
+    internal_attack_prob: float = 0.1        # a sub-argument rebuts its parent conclusion
+    share_prob: float = 0.0                  # an extra sub-argument reuses an existing
+                                             # node (shared parent). 0 = forest of trees
+                                             # (polytree); > 0 makes real cycles / collapses
+                                             # d-sep groups, so loopy BP turns approximate.
+    undercut_prob: float = 0.15              # per edge
+    undermine_prob: float = 0.15             # per ordinary premise
+    strict_prob: float = 0.1                 # per internal support edge (-> noisy-OR)
+    axiom_prob: float = 0.2                  # per leaf
+    attacker_depth_range: tuple = (1, 1)     # undercutter / underminer depth (1 = bare premise)
+    n_claims_range: Optional[tuple] = None   # constructive total argument-claim band
+    root_prior: Optional[float] = None       # None -> uniform in [0.3, 0.7]
+    leaf_prior_range: tuple = (0.3, 0.75)
+    mid_prior_range: tuple = (0.1, 0.25)     # intermediate conclusion prior
+    attacker_prior_range: tuple = (0.05, 0.4)  # bare undercutter / underminer prior
+    support_lr_range: tuple = (3.0, 15.0)    # root support edges (log-uniform, lr > 1)
+    internal_lr_range: tuple = (1.5, 12.0)   # internal support edges (lr > 1)
+    attack_lr_range: tuple = (1 / 15, 1 / 3)  # reciprocal of support -> symmetric |log lr|
+
+    @property
+    def n_groups(self) -> int:
+        return self.n_support + self.n_attack
+
+    def __post_init__(self):
+        if self.n_support < 0 or self.n_attack < 0:
+            raise ValueError("n_support and n_attack must be >= 0")
+        if self.n_groups < 1:
+            raise ValueError("need at least one branch (n_support + n_attack >= 1)")
+        if self.depths is not None and len(self.depths) != self.n_groups:
+            raise ValueError(
+                f"depths has {len(self.depths)} entries but n_groups is {self.n_groups}"
+            )
+
+
+@dataclass
+class DifficultyTargets:
+    """What an accepted graph must satisfy (None = unconstrained)."""
+
+    threshold: float = 0.5
+    posterior_side: Optional[str] = None     # 'above' | 'below' | None (coarse)
+    target_posterior: Optional[float] = None  # calibrate the root prior to hit this
+    posterior_tol: float = 0.02              # accepted band around target_posterior
+    min_manipulability: Optional[float] = None
+    min_depth: Optional[int] = None          # realized longest input-path into the root
+    d_sep_groups: Optional[int] = None       # realized d-separated group count (for share mode)
+
+
+class ArgumentGenerator:
+    """Builds one argument. Add branches (each its own d-separated group), then
+    `build()` for the `Argument`. Construct with a seeded `random.Random` for
+    reproducibility."""
+
+    def __init__(self, rng: random.Random, params: Optional[StructuralParams] = None):
+        self.rng = rng
+        self.p = params or StructuralParams()
+        if self.p.n_groups < 1:
+            raise ValueError("need at least one branch")
+        self._n = 0
+        self._uc_nodes: set = set()         # nodes inside undercutter/underminer subgraphs
+        prior = (self.p.root_prior if self.p.root_prior is not None
+                 else round(rng.uniform(0.3, 0.7), 4))
+        self.root = Conclusion("Root", prior=prior)
+
+    # --- branch-level API (the "add a d-separated group" primitive) ---------
+
+    def add_support_branch(self, depth: Optional[int] = None) -> None:
+        self._branch(self.root, "support", depth or self._depth())
+
+    def add_attack_branch(self, depth: Optional[int] = None) -> None:
+        self._branch(self.root, "attack", depth or self._depth())
+
+    def build(self) -> Argument:
+        return self.root.assemble()
+
+    def claim_count(self) -> int:
+        return sum(1 for c in _reachable(self.root) if isinstance(c, _Claim))
+
+    def sprout(self) -> None:
+        """Add one depth-1 supporting premise to a random conclusion — grows the
+        claim count by exactly one, for constructive size control."""
+        conclusions = [c for c in _reachable(self.root) if isinstance(c, Conclusion)]
+        self.rng.choice(conclusions).support(self._leaf_premise(),
+                                             self._lr(*self.p.internal_lr_range))
+
+    # --- internals ----------------------------------------------------------
+
+    def _name(self) -> str:
+        self._n += 1
+        return f"Node {self._n}"
+
+    def _depth(self) -> int:
+        return self.rng.randint(self.p.min_depth, self.p.max_depth)
+
+    def _lr(self, lo: float, hi: float) -> float:
+        return round(math.exp(self.rng.uniform(math.log(lo), math.log(hi))), 4)
+
+    def _prior(self, rng_range: tuple) -> float:
+        return round(self.rng.uniform(*rng_range), 4)
+
+    def _leaf_premise(self) -> Premise:
+        return Premise(self._name(), prior=self._prior(self.p.leaf_prior_range))
+
+    def _leaf(self):
+        if self.rng.random() < self.p.axiom_prob:
+            return Axiom(self._name())
+        return self._leaf_premise()
+
+    def _branch(self, target, polarity: str, depth: int):
+        src = self._subtree(depth - 1)
+        self._attach(target, src, polarity)
+        self._decorate(target, src)
+        return src
+
+    def _subtree(self, height: int, *, isolated: bool = False):
+        """A fresh sub-argument; returns its root (a premise at height 0, else a
+        conclusion fed by `_populate`). `height` is hops above the root.
+        `isolated=True` (attacker sub-arguments) disables decoration and sharing, so
+        the subgraph stays fully disjoint."""
+        if height <= 0:
+            return self._leaf()
+        root = Conclusion(self._name(), prior=self._prior(self.p.mid_prior_range))
+        self._populate(root, height, isolated=isolated)
+        return root
+
+    def _populate(self, conclusion, height: int, *, isolated: bool = False) -> None:
+        """Give `conclusion` its sub-arguments: the first continues to `height - 1`
+        (so the height is realized) and is always fresh; up to `max_fanin` shallower
+        extras follow (a tree). With `share_prob > 0` an extra may *reuse* an existing
+        node instead of a fresh one — a shared parent, which makes the graph
+        non-polytree (a within-branch cycle) or collapses d-sep groups (across
+        branches). Each child attaches by support, or by attack with
+        `internal_attack_prob`."""
+        n_extra = sum(self.rng.random() < self.p.fanin_prob
+                      for _ in range(self.p.max_fanin))
+        heights = [height - 1] + [self.rng.randint(0, height - 1) for _ in range(n_extra)]
+        for j, h in enumerate(heights):
+            child, shared = self._child(conclusion, h, allow_share=not isolated and j > 0)
+            polarity = ("attack" if self.rng.random() < self.p.internal_attack_prob
+                        else "support")
+            self._attach(conclusion, child, polarity)
+            if not isolated and not shared:        # a reused node already has structure
+                self._decorate(conclusion, child)
+
+    def _child(self, conclusion, height: int, *, allow_share: bool):
+        """Either reuse an eligible existing node (probability `share_prob`) or build a
+        fresh sub-argument. Returns `(node, was_shared)`."""
+        if allow_share and self.p.share_prob > 0 and self.rng.random() < self.p.share_prob:
+            role = Premise if height <= 0 else Conclusion
+            cands = self._share_candidates(role, conclusion)
+            if cands:
+                return self.rng.choice(cands), True
+        return self._subtree(height), False
+
+    def _share_candidates(self, role, conclusion):
+        """Existing nodes that may legally become a new parent of `conclusion`:
+        matching role, not the root, not already a source of it, not inside an
+        undercutter subgraph, and not an ancestor of it (which would make a directed
+        cycle). Reuse is what turns the forest into a DAG with shared parents."""
+        existing = {s for s, _lr, _k in conclusion._edges} | set(conclusion._strict)
+        out = []
+        for n in _reachable(self.root):
+            if not isinstance(n, role) or n is self.root or n is conclusion:
+                continue
+            if n in self._uc_nodes or n in existing:
+                continue
+            if conclusion in _reachable(n):            # n is an ancestor -> cycle
+                continue
+            out.append(n)
+        return out
+
+    def _mark_uc(self, node) -> None:
+        for c in _reachable(node):
+            if isinstance(c, _Claim):
+                self._uc_nodes.add(c)
+
+    def _attach(self, downstream, upstream, polarity: str) -> None:
+        """Wire `upstream` into `downstream` with the right typed edge."""
+        if polarity == "support":
+            # strict only on an internal edge from a non-axiom: a strict root would
+            # divorce every defeasible branch into D and break the d-sep count.
+            if (downstream is not self.root and not isinstance(upstream, Axiom)
+                    and self.rng.random() < self.p.strict_prob):
+                downstream.strict(upstream)
+            else:
+                lr_range = (self.p.support_lr_range if downstream is self.root
+                            else self.p.internal_lr_range)
+                downstream.support(upstream, self._lr(*lr_range))
+        else:                                               # attack
+            lr = self._lr(*self.p.attack_lr_range)
+            if isinstance(downstream, Premise):
+                downstream.undermine(by=upstream, lr=lr)    # attack on a premise
+            else:
+                downstream.rebut(upstream, lr=lr)           # attack on a conclusion
+
+    def _attacker(self):
+        """A fresh, disjoint undercutter / underminer: a bare premise at depth 1, or
+        its own small sub-argument up to `attacker_depth_range`."""
+        d = self.rng.randint(*self.p.attacker_depth_range)
+        if d <= 1:
+            return Premise(self._name(), prior=self._prior(self.p.attacker_prior_range))
+        root = Conclusion(self._name(), prior=self._prior(self.p.mid_prior_range))
+        self._populate(root, d - 1, isolated=True)      # disjoint: no decorate, no share
+        return root
+
+    def _decorate(self, downstream, source) -> None:
+        """Optionally undercut the `source -> downstream` edge, and optionally
+        undermine `source` if it is an ordinary premise. Attacker subgraphs are
+        marked so sharing never reaches into or out of them."""
+        if self.rng.random() < self.p.undercut_prob:
+            by = self._attacker()
+            downstream.undercut(source, by=by)
+            self._mark_uc(by)
+        if (isinstance(source, Premise) and not isinstance(source, Axiom)
+                and self.rng.random() < self.p.undermine_prob):
+            by = self._attacker()
+            source.undermine(by=by, lr=self._lr(*self.p.attack_lr_range))
+            self._mark_uc(by)
+
+
+def _calibrate_root_prior(root, target: float, tol: float,
+                          lo: float = 0.02, hi: float = 0.98, iters: int = 60) -> bool:
+    """Bisect the root's prior so its posterior hits `target` (the posterior is
+    monotone increasing in the prior). Mutates `root.prior`; returns True if a
+    prior in `[lo, hi]` lands within `tol`, else False (unreachable for this
+    structure — resample). Cheap: the graph is a polytree, so loopy BP is exact.
+
+    This is the dependency-free calibration fallback. It tunes one parameter (the
+    root prior) and may push it outside the nominal structural range; the planned
+    JAX path (docs/generation.md) does a projected multi-parameter solve instead.
+    """
+    from ..core import ExactSolver, LoopySolver
+    from ..metrics import is_polytree
+
+    def posterior(p: float) -> float:
+        root.prior = float(p)
+        bn = root.compile()
+        solver = LoopySolver if is_polytree(bn) else ExactSolver   # share mode -> exact
+        return solver(bn).prob(root, 1)
+
+    if not posterior(lo) - tol <= target <= posterior(hi) + tol:
+        return False
+    for _ in range(iters):
+        mid = 0.5 * (lo + hi)
+        pm = posterior(mid)
+        if abs(pm - target) <= tol:
+            return True
+        if pm < target:
+            lo = mid
+        else:
+            hi = mid
+    return abs(posterior(0.5 * (lo + hi)) - target) <= tol
+
+
+def _build_one(rng, params) -> "ArgumentGenerator":
+    """One proposed graph: the branches at their drawn/exact depths, then grown
+    constructively to `n_claims_range`'s lower bound if set."""
+    g = ArgumentGenerator(rng, params)
+    if params.depths is not None:
+        for d in params.depths[:params.n_support]:
+            g.add_support_branch(depth=d)
+        for d in params.depths[params.n_support:]:
+            g.add_attack_branch(depth=d)
+    else:
+        for _ in range(params.n_support):
+            g.add_support_branch()
+        for _ in range(params.n_attack):
+            g.add_attack_branch()
+    if params.n_claims_range is not None:
+        lo, _hi = params.n_claims_range
+        guard = 0
+        while g.claim_count() < lo and guard < 1000:
+            g.sprout()
+            guard += 1
+    return g
+
+
+def generate(seed: Optional[int] = None, *,
+             structural: Optional[StructuralParams] = None,
+             targets: Optional[DifficultyTargets] = None,
+             max_attempts: int = 200, verbose: bool = False) -> Argument:
+    """Rejection-sample an `Argument` meeting `targets`. The structural shape
+    (`n_support`/`n_attack`, depth, features) is set directly; the difficulty
+    targets are screened, and `target_posterior` is reached by calibrating the root
+    prior. Raises `RuntimeError` if no graph passes within `max_attempts`."""
+    from ..core import ExactSolver, LoopySolver
+    from ..metrics import d_separated_groups, is_polytree, manipulability, max_depth
+
+    params = structural or StructuralParams()
+    tgt = targets or DifficultyTargets()
+    base = random.Random(seed)
+
+    for attempt in range(1, max_attempts + 1):
+        rng = random.Random(base.randint(0, 2**31))
+        g = _build_one(rng, params)
+
+        if params.n_claims_range is not None:
+            _lo, hi = params.n_claims_range
+            if g.claim_count() > hi:
+                if verbose:
+                    print(f"attempt {attempt}: {g.claim_count()} claims > {hi}")
+                continue
+
+        if (tgt.target_posterior is not None
+                and not _calibrate_root_prior(g.root, tgt.target_posterior,
+                                              tgt.posterior_tol)):
+            if verbose:
+                print(f"attempt {attempt}: target {tgt.target_posterior} unreachable")
+            continue
+
+        arg = g.build()
+        bn = arg.bn
+        # a polytree (no sharing) -> loopy BP is exact and linear; sharing makes a
+        # cycle, so fall back to the exact solver (keep share-mode graphs small).
+        p_root = (LoopySolver if is_polytree(bn) else ExactSolver)(bn).prob(arg.target, 1)
+
+        if tgt.d_sep_groups is not None and \
+                len(d_separated_groups(bn, arg.target)) != tgt.d_sep_groups:
+            continue
+        if tgt.posterior_side == "above" and not p_root > tgt.threshold:
+            continue
+        if tgt.posterior_side == "below" and not p_root < tgt.threshold:
+            continue
+        if (tgt.target_posterior is not None
+                and abs(p_root - tgt.target_posterior) > tgt.posterior_tol):
+            continue
+        if tgt.min_depth is not None and max_depth(arg.bn, arg.target) < tgt.min_depth:
+            if verbose:
+                print(f"attempt {attempt}: depth {max_depth(arg.bn, arg.target)} "
+                      f"< {tgt.min_depth}")
+            continue
+        if tgt.min_manipulability is not None:
+            m = manipulability(arg.bn, arg.target)
+            if m < tgt.min_manipulability:
+                if verbose:
+                    print(f"attempt {attempt}: manipulability {m:.3f} < "
+                          f"{tgt.min_manipulability}")
+                continue
+
+        if verbose:
+            print(f"attempt {attempt}: accepted (P={p_root:.3f})")
+        return arg
+
+    raise RuntimeError(
+        f"no graph met the targets in {max_attempts} attempts; relax the targets "
+        "(move threshold toward 0.5, widen posterior_tol, lower min_manipulability/"
+        "min_depth) or raise max_attempts"
+    )

probability_flow/aspic/handle.py

@@ -0,0 +1,281 @@
+"""The `Argument` handle: what `target.assemble()` returns.
+
+Authoring stays in `argument.py` (free constructors, fluent edges on the
+downstream node). Once an argument is built, `assemble()` wraps its target in an
+`Argument`, the home for everything you do *with* a finished argument: serialize
+it (`to_json` / `from_json` / `save` / `load`), reach the compiled network
+(`.bn`), query a posterior, and measure it (the `metrics` seam).
+
+Serialization is at the *argument* level, not the compiled BN: the JSON carries
+the typed edges (support / rebut / strict / undermine) and the undercut as an
+`undercutter_ids` field on the edge it attacks, and `from_json` recompiles the BN
+deterministically. The lowered splice / divorced-D helper nodes never appear.
+
+The schema is the team-agreed one in `docs/aspic.md`. The metric fields
+(`input_groups_sizes` from d-separation, `min_posterior` / `max_posterior` from
+the manipulability range) are filled by the `metrics` seam; `revealable_to_judge`
+and `desc` are carried verbatim but the library does not interpret them.
+"""
+from __future__ import annotations
+
+import json
+import re
+import warnings
+from typing import TYPE_CHECKING, Optional
+
+from ..core import ExactSolver
+from .compile import _reachable
+
+if TYPE_CHECKING:
+    from ..core import BayesianNetwork, Node
+    from .argument import _Claim
+
+SCHEMA_VERSION = "0.1"
+
+# Above this many nodes the brute-force ExactSolver fallback (2**n joint
+# enumeration, used only on non-polytree arguments) gets painfully slow. See the
+# "Known issues" note in docs/ROADMAP.md.
+_EXACT_FALLBACK_WARN_NODES = 22
+
+# argument-edge kind (stored on the node) <-> serialized "type"
+_KIND_TO_TYPE = {"support": "support/defeas", "rebut": "rebut", "undermine": "undermine"}
+_TYPE_TO_KIND = {v: k for k, v in _KIND_TO_TYPE.items()}
+
+
+def _slugify(label: str) -> str:
+    return re.sub(r"[^a-z0-9]+", "-", label.lower()).strip("-") or "node"
+
+
+def _assign_ids(claims: list["_Claim"]) -> dict["_Claim", str]:
+    """A stable readable id per claim: the slugified label, with a numeric suffix
+    on collision. Assignment is sorted by slug so the same multiset of labels maps
+    to the same ids regardless of graph-traversal order (round-trip stable)."""
+    used: dict[str, int] = {}
+    ids: dict["_Claim", str] = {}
+    for c in sorted(claims, key=lambda n: _slugify(n.name)):
+        base = _slugify(c.name)
+        n = used.get(base, 0)
+        ids[c] = base if n == 0 else f"{base}-{n + 1}"
+        used[base] = n + 1
+    return ids
+
+
+class Argument:
+    """A finished argument, rooted at its target. Construct via `target.assemble()`."""
+
+    def __init__(self, target: "_Claim"):
+        self.target = target
+        self._bn: Optional["BayesianNetwork"] = None
+        self._solver = None                     # cached; see the `solver` property
+        self._edge_meta: dict[str, dict] = {}   # edge id -> {label, revealable_to_judge}
+
+    # --- compiled network and queries -------------------------------------
+
+    @property
+    def bn(self) -> "BayesianNetwork":
+        """The compiled `BayesianNetwork` (built once, then cached)."""
+        if self._bn is None:
+            self._bn = self.target.compile()
+        return self._bn
+
+    @property
+    def solver(self):
+        """The ground-truth solver for this argument, chosen by topology:
+        `LoopySolver` on a polytree (provably exact there, linear in the graph,
+        and one propagation answers every node), `ExactSolver` otherwise (loops;
+        exponential, so only viable on small graphs). Built once, then cached —
+        `LoopySolver` reuses its message passing across queries."""
+        if self._solver is None:
+            from ..core import LoopySolver
+            from ..metrics import is_polytree
+
+            if is_polytree(self.bn):
+                self._solver = LoopySolver(self.bn)
+            else:
+                n = len(self.bn.nodes)
+                if n > _EXACT_FALLBACK_WARN_NODES:
+                    warnings.warn(
+                        f"this argument is not a polytree, so it is solved by "
+                        f"brute-force enumeration of all 2**{n} joint states, which "
+                        "is slow at this size. Keep shared / loopy graphs small "
+                        "until the loopy-BP robustness work lands (docs/ROADMAP.md).",
+                        stacklevel=2,
+                    )
+                self._solver = ExactSolver(self.bn)
+        return self._solver
+
+    def posterior(self, node: "Node", evidence=None) -> float:
+        """`P(node = 1 | evidence)` under the compiled network (see `solver` for
+        how the solver is chosen)."""
+        return self.solver.prob(node, 1, evidence=evidence)
+
+    def render(self, **kwargs):
+        """Draw the argument view (see `aspic.visualization`); `self.bn.render()`
+        draws the compiled network instead."""
+        return self.target.render(**kwargs)
+
+    # --- argument-level metrics (delegating to the metrics seam) ----------
+
+    def input_groups_sizes(self, node: "Node") -> Optional[list[int]]:
+        """Sorted evidence-mass sizes of `node`'s d-separated input groups — one
+        entry per independent argument branch, counting **only argument claims**.
+        The lowered helper nodes (the undercut splice `X`, the divorced `D`) are
+        hidden here as everywhere in the argument view (decision 8), so a branch
+        whose cone is pure machinery (a prior-only divorced `D`) drops out. `None`
+        for a node with no inputs (a premise). Sorted for round-trip stability.
+
+        The underlying `metrics.d_separated_groups` stays BN-level (its `g.nodes`
+        is the full compiled cone); the argument-level filtering happens here, the
+        seam where the abstracted view is the handle's job."""
+        from ..metrics import d_separated_groups
+        from .argument import _Claim
+
+        if not self.bn.compiled_cpd(node).inputs:
+            return None
+        sizes = []
+        for g in d_separated_groups(self.bn, node):
+            claims = sum(1 for x in g.nodes if isinstance(x, _Claim))
+            if claims:                       # drop pure-helper branches (prior-only D)
+                sizes.append(claims)
+        return sorted(sizes)
+
+    def posterior_range(self, node: "Node") -> tuple[float, float]:
+        """(min, max) posterior `node` could be pushed to over partial reveals of
+        its upstream evidence — the manipulability range. The cheap polynomial outer
+        bound; see `metrics.posterior_range` for the reveal model."""
+        from ..metrics import posterior_range
+
+        return posterior_range(self.bn, node)
+
+    # --- serialization ----------------------------------------------------
+
+    def to_dict(self) -> dict:
+        """The argument as a plain dict matching the team schema (`docs/aspic.md`)."""
+        from .argument import Axiom, Premise, _Claim
+
+        bn = self.bn
+        solver = self.solver
+        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:
+            raise TypeError(
+                "Argument.to_dict supports arguments built from Premise / Axiom / "
+                f"Conclusion only; found plain node(s): {[n.name for n in non_claim]}"
+            )
+        ids = _assign_ids(claims)
+
+        def type_of(c: "_Claim") -> str:
+            if c is self.target:
+                return "root"
+            if isinstance(c, Axiom):
+                return "axiomatic premise"
+            if isinstance(c, Premise):
+                return "premise"
+            return "conclusion"
+
+        def cpd_type(c: "_Claim") -> str:
+            name = type(bn.compiled_cpd(c).cpd).__name__
+            return name[:-3] if name.endswith("CPD") else name
+
+        def node_dict(c: "_Claim") -> dict:
+            lo, hi = self.posterior_range(c)
+            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),
+                "input_groups_sizes": self.input_groups_sizes(c),
+                "cpd_type": cpd_type(c),
+                "revealable_to_judge": c.revealable_to_judge,
+            }
+
+        nodes = [node_dict(c) for c in claims]
+
+        edges = []
+        for c in claims:
+            undercutters: dict[int, list["_Claim"]] = {}
+            for src, by in c._undercuts:
+                undercutters.setdefault(id(src), []).append(by)
+
+            def edge(src, etype, lr):
+                eid = f"{ids[src]}->{ids[c]}"
+                meta = self._edge_meta.get(eid, {})
+                return {
+                    "id": eid,
+                    "type": etype,
+                    "label": meta.get("label"),
+                    "source": ids[src],
+                    "target": ids[c],
+                    "undercutter_ids": [ids[u] for u in undercutters.get(id(src), [])],
+                    "lr": None if lr is None else float(lr),
+                    "revealable_to_judge": meta.get("revealable_to_judge"),
+                }
+
+            for src, lr, kind in c._edges:
+                edges.append(edge(src, _KIND_TO_TYPE[kind], lr))
+            for src in c._strict:
+                edges.append(edge(src, "strict", None))
+
+        return {"version": SCHEMA_VERSION, "target": ids[self.target],
+                "nodes": nodes, "edges": edges}
+
+    def to_json(self, *, indent: int = 2) -> str:
+        return json.dumps(self.to_dict(), indent=indent)
+
+    def save(self, path: str) -> None:
+        with open(path, "w") as f:
+            f.write(self.to_json())
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "Argument":
+        """Rebuild an `Argument` from a `to_dict` payload. The compiled BN is
+        recomputed lazily on first `.bn` access, so a round trip reproduces it."""
+        from .argument import Axiom, Conclusion, Premise
+
+        by_id: dict[str, "_Claim"] = {}
+        for nd in data["nodes"]:
+            t = nd["type"]
+            if t == "axiomatic premise":
+                node: "_Claim" = Axiom(nd["label"])
+            elif t == "premise":
+                node = Premise(nd["label"], prior=nd.get("prior", 0.5))
+            else:                                   # "conclusion" or "root"
+                node = Conclusion(nd["label"], prior=nd.get("prior", 0.5))
+            node.desc = nd.get("desc")
+            node.revealable_to_judge = nd.get("revealable_to_judge")
+            by_id[nd["id"]] = node
+
+        edge_meta: dict[str, dict] = {}
+        for ed in data["edges"]:
+            src, tgt = by_id[ed["source"]], by_id[ed["target"]]
+            etype, lr = ed["type"], ed.get("lr")
+            if etype == "strict":
+                tgt.strict(src)
+            elif etype == "undermine":
+                tgt.undermine(by=src, lr=lr)
+            elif etype in _TYPE_TO_KIND:            # support/defeas or rebut
+                (tgt.support if etype == "support/defeas" else tgt.rebut)(src, lr)
+            else:
+                raise ValueError(f"unknown edge type {etype!r}")
+            for uid in ed.get("undercutter_ids", []):
+                tgt.undercut(src, by=by_id[uid])
+            if ed.get("label") is not None or ed.get("revealable_to_judge") is not None:
+                edge_meta[ed["id"]] = {"label": ed.get("label"),
+                                       "revealable_to_judge": ed.get("revealable_to_judge")}
+
+        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))
+
+    @classmethod
+    def load(cls, path: str) -> "Argument":
+        with open(path) as f:
+            return cls.from_json(f.read())