Diagnostics

def can_fail(source: str) -> bool:
    """Tell whether a Python script has a reachable way to fail: an ``assert``, a ``raise``, or a non-zero exit.

    Code that a constant condition makes unreachable is ignored first: the body of ``if False:``,
    ``if 0:`` or ``while False:``, the ``else`` of ``if True:``, the dead branch of a conditional
    expression, and an ``assert`` of a constantly true condition such as ``assert True``. A condition
    counts as constant when it is a literal, the ``not`` of a constant condition, or a conditional
    expression whose condition and taken branch are constant, at any depth of nesting, so
    ``if (False if True else False):`` is pruned like ``if False:`` and
    ``assert (True if True else False)`` cannot fail; a check behind any other condition is taken to be
    reachable. A script that does not parse has no checked failure path, only a crash, and counts as
    unable to fail.

    Args:
        source: The script's text.

    Returns:
        ``True`` when the reachable code holds an ``assert`` or ``raise`` statement, or an exit call
        (``sys.exit``, ``os._exit``, ``exit`` or ``quit``) whose argument is not ``0`` or ``None``.
    """
    try:
        tree = _DeadCode().visit(ast.parse(source))
    except (SyntaxError, ValueError):
        return False
    return any(
        isinstance(node, ast.Assert | ast.Raise) or (isinstance(node, ast.Call) and _exits_nonzero(node))
        for node in ast.walk(tree)
    )

def correlated_support(graph: Graph, min_supports: int = DEFAULT_MIN_SUPPORTS) -> list[Finding]:
    """Find supports of one node that share a source but no common ancestor.

    The ``supports`` relations into a node combine as a noisy OR of independent reasons: ten of
    strength 0.2 into a node of base 0 give it 1 - 0.8^10, about 0.893. Reasons that come from one
    source are rarely independent, and nothing in the graph says so unless they share an ancestor. Two
    supporting variables share a source when a node of each is anchored in the same document, or
    points at the same node through an ``authored_by`` or ``derived_from`` annotation. A group of at
    least ``min_supports`` supporting variables of one node that share a source is reported when no
    variable is a common ancestor of them: an ancestor, through chains of ``requires``, ``supports``
    or ``refutes`` relations, of every one of them, or one of them that is an ancestor of all the
    others, as in ``p0 supports p1``, ``p0 supports claim``, ``p1 supports claim``. Either way the
    graph already makes them depend on one variable, so inference does not count them as independent.
    A relation of strength exactly 0 does not make a parent, nor a support: it leaves the child's
    probability the same whatever the parent's value. Nor is a fixed point a common ancestor, nor an
    ancestor through it: a variable that always takes the same value, whether it has no parents and
    a base of mean exactly 0 or 1 or has a table that gives it that value whatever its parents are,
    as with a base of 1 and only ``supports`` parents, correlates nothing and passes nothing on.
    The usual fix is a common parent: a proposition such as "this source's unverified reasoning
    is sound", which each of them requires with strength 1, so that they fail together. A node of
    base b with no other parents then gets at most b + (1 - b) c from the group, c the credence of
    the proposition, however large the group.

    Nodes merged by ``equivalent`` relations are one variable, named after the earliest of them, with
    the sources of all of them. A group that shares several sources is reported once, under the first.

    Several ``supports`` relations from one variable into the same node, for example one from each
    of two merged nodes, are separate terms of the noisy OR too: two of strength 0.2 lift a node of
    base 0 to 0.36 where one gives 0.2. At least ``min_supports`` of them of nonzero strength are
    reported whatever the variable's parents, since no common parent can correlate terms that
    already share their only input; the fix is one relation in their place.

    Args:
        graph: The graph.
        min_supports: The smallest group reported, at least 2; the default, 2, reports any two.

    Returns:
        One finding per node and group, the nodes in insertion order, and for each node its groups
        before its repeated supports. Its id is ``correlated-support:<node>:<kind>:<source>``, where
        the kind is ``document`` or the annotation type, or ``variable`` with the supporting variable
        as the source for supports repeated from one variable. Its nodes are the supported node, then
        the group or the variable; its relations are their ``supports`` relations of nonzero strength
        into the node. It has no value; its details are
        ``supports``, the size of the group or the number of relations, and ``min_supports``.

    Raises:
        ValidationError: If ``min_supports`` is not an integer >= 2.
    """
    count = _min_supports(min_supports)
    members = inference_sets(graph)
    root = {node_id: representative for representative, ids in members.items() for node_id in ids}
    provenance = _provenance(graph, members, root)
    parents: dict[str, set[str]] = {}
    lineage: dict[str, set[str]] = {}
    supports: dict[str, dict[str, list[str]]] = {}
    terms: dict[str, list[tuple[str, str, Fraction]]] = {}
    for relation in graph.relations.values():
        if relation.type in STRENGTH_TYPES:
            parent, child = root[relation.source], root[relation.target]
            # A term of strength 0 multiplies the child's table by 1 - 0 = 1 at both of the parent's
            # values, so it makes the parent no cause of the child; a Beta strength has a positive mean.
            if relation.strength is not None and relation.strength.mean > 0.0:
                parents.setdefault(child, set()).add(parent)
                terms.setdefault(child, []).append((relation.type, parent, Fraction(relation.strength.mean)))
                if relation.type == SUPPORTS:
                    supports.setdefault(child, {}).setdefault(parent, []).append(relation.id)
    fixed = _fixed_points(graph, members, parents, terms)
    # A fixed variable takes its value whatever its parents are, so nothing above it reaches its descendants.
    effective = {child: own for child, own in parents.items() if child not in fixed}
    findings: list[Finding] = []
    for target in members:
        by_parent = supports.get(target, {})
        sharing: dict[tuple[str, str], list[str]] = {}
        for parent in by_parent:
            for key in provenance[parent]:
                sharing.setdefault(key, []).append(parent)
        groups: dict[tuple[str, ...], list[tuple[str, str]]] = {}
        for key, group in sharing.items():
            common = set.intersection(*(_lineage(parent, effective, lineage) for parent in group))
            if len(group) >= count and not common - fixed.keys():
                groups.setdefault(tuple(group), []).append(key)
        for group, keys in groups.items():
            names = ", ".join(repr(parent) for parent in group)
            findings.append(
                Finding(
                    id=f"{CORRELATED_SUPPORT}:{target}:{keys[0][0]}:{keys[0][1]}",
                    diagnostic=CORRELATED_SUPPORT,
                    message=(
                        f"node {target!r} has {len(group)} supports, {names}, that share "
                        f"{' and '.join(_render(key) for key in keys)} but no common ancestor: inference counts "
                        "them as independent reasons; if they rest on one source's reasoning, add a proposition "
                        "for it that each of them requires"
                    ),
                    nodes=(target, *group),
                    relations=tuple(relation for parent in group for relation in by_parent[parent]),
                    details={"supports": float(len(group)), "min_supports": float(count)},
                )
            )
        findings.extend(
            Finding(
                id=f"{CORRELATED_SUPPORT}:{target}:variable:{parent}",
                diagnostic=CORRELATED_SUPPORT,
                message=(
                    f"node {target!r} has {len(relations)} supports from one variable, "
                    f"{_describe(members[parent])}: inference counts them as independent reasons; "
                    "if they are one reason, replace them with a single supports relation"
                ),
                nodes=(target, parent),
                relations=tuple(relations),
                details={"supports": float(len(relations)), "min_supports": float(count)},
            )
            for parent, relations in by_parent.items()
            if len(relations) >= count
        )
    return findings

def crux(
    network: Network,
    target: str,
    *,
    evidence: Mapping[str, bool] | None = None,
    engine: Engine | None = None,
) -> list[Finding]:
    """Rank the parameters by ``|dP(target | evidence)/dθ| * sd(θ)``.

    A parameter is a crux when the target depends on it *and* it is uncertain: a steep derivative on
    a ``Point`` parameter, or a wide credence the target ignores, both score zero. This is the
    primary weak-point ranking. Under evidence, sd(θ) is still that of the parameter's own credence:
    the parameters are not updated on the evidence, as they are not for the uncertainty bands.

    Args:
        network: The network.
        target: The id of the target node.
        evidence: Node ids and their observed values; none by default.
        engine: The exact engine; variable elimination by default.

    Returns:
        One finding per parameter, largest crux first; or a single structural finding, with no
        value, when no parameter the target depends on is uncertain, as when every one is a
        ``Point``.

    Raises:
        ValidationError: If ``target`` or an evidence node is not an inference variable of the
            network, or the evidence observes the target.
        ZeroProbabilityError: If the evidence and the ``exclusive`` constraints have probability zero.
    """
    slopes = derivatives(network, target, evidence=evidence, engine=engine)
    return crux_findings(network, target, slopes, evidence=evidence)

def dependencies(graph: Graph, target: str) -> list[Relation]:
    """Find the inferential relations a target depends on.

    These are the ``requires``, ``supports`` and ``refutes`` relations into the target or into any
    node it depends on, and the ``equivalent`` and ``exclusive`` relations that touch either; the
    other end of each also becomes a node the target depends on.

    Args:
        graph: The graph.
        target: The target node's id.

    Returns:
        The relations, in the graph's order.
    """
    reached = {target}
    found: set[str] = set()
    grew = True
    while grew:
        grew = False
        for relation in graph.relations.values():
            if relation.id in found:
                continue
            if relation.type in STRENGTH_TYPES:
                touches = relation.target in reached
            elif relation.type in {EQUIVALENT, EXCLUSIVE}:
                touches = relation.source in reached or relation.target in reached
            else:
                continue
            if touches:
                found.add(relation.id)
                reached.update((relation.source, relation.target))
                grew = True
    return [relation for relation in graph.relations.values() if relation.id in found]

def derivatives(
    network: Network,
    target: str,
    *,
    evidence: Mapping[str, bool] | None = None,
    engine: Engine | None = None,
) -> dict[ParameterKey, float]:
    """Compute ``dP(target | evidence)/dθ`` exactly for every parameter θ of the network.

    See the module documentation for why this is exact. Each derivative is taken at the value the
    parameter currently holds, with every other parameter held at its own. With evidence the
    derivative is the quotient rule on two multilinear evaluations, not the two-point difference.

    Args:
        network: The network.
        target: The id of the target node.
        evidence: Node ids and their observed values; none by default.
        engine: The exact engine; variable elimination by default.

    Returns:
        The derivative of ``P(target = true | evidence)`` by parameter, in the order
        ``network.parameters`` lists them.

    Raises:
        ValidationError: If ``target`` or an evidence node is not an inference variable of the
            network, or the evidence observes the target.
        ZeroProbabilityError: If the evidence and the ``exclusive`` constraints have probability zero.
    """
    engine = engine or VariableElimination()
    query = _observed(network, target, evidence)
    index = network.index(target)
    conditions = _conditions(network, query.evidence)
    numerator, denominator = _parts(network, index, conditions, engine)
    if denominator <= 0.0:
        msg = "the evidence, together with the exclusive constraints, has probability zero"
        raise ZeroProbabilityError(msg)
    slopes: dict[ParameterKey, float] = {}
    for key in network.parameters:
        low_n, low_d = _parts(network.with_parameters({key: 0.0}), index, conditions, engine)
        high_n, high_d = _parts(network.with_parameters({key: 1.0}), index, conditions, engine)
        slopes[key] = ((high_n - low_n) * denominator - numerator * (high_d - low_d)) / denominator**2
    return slopes

def diagnose(  # noqa: PLR0913 - the options after the target are keyword-only
    graph: Graph,
    target: str | None = None,
    *,
    evidence: Mapping[str, bool] | None = None,
    claim_threshold: float = DEFAULT_CLAIM_THRESHOLD,
    failure_threshold: float = DEFAULT_FAILURE_THRESHOLD,
    min_supports: int = DEFAULT_MIN_SUPPORTS,
    engine: Engine | None = None,
) -> list[Finding]:
    """Run the diagnostics that apply to a graph and, optionally, a target node.

    The structural checks (missing parameters, unanchored variables, correlated supports) always
    run. If a parameter is missing the graph cannot be compiled, and the report stops there. Otherwise the stated credences
    are compared with the computed ones, and, when a target is given, its sensitivity, crux,
    single points of failure, failure impact and value of information follow. ``diagnose_many``
    does the same for several targets, running the graph-wide checks once.

    With evidence every inference diagnostic is taken given it: the computed credences are
    ``P(X | evidence)``, the sensitivities and cruxes are derivatives of ``P(target | evidence)``,
    the single points of failure and the failure impact compare ``P(target | do(Y = false), evidence)``
    with ``P(target | evidence)``, and the value of information is ``I(target; Y | evidence)``. Observed
    variables are left out of the comparisons and rankings over nodes, and the target may not be
    observed. Without evidence the report is the one for the graph before anything is observed.

    Args:
        graph: The graph.
        target: The id of the node whose weak points are wanted, if any.
        evidence: Node ids and their observed values; none by default.
        claim_threshold: The threshold passed to ``claims``, a gap in natural log-odds; the default,
            ``2 ln(11 / 9)``, is a convention of this package.
        failure_threshold: The threshold passed to ``single_points_of_failure``, and marked in the
            ``failure_impact`` ranking, a fraction of the target's own probability; the default, 0.1,
            is a convention of this package. A premise behind one ``requires`` of strength r crosses
            it only if r > 1 - threshold.
        min_supports: The smallest group passed to ``correlated_support``, at least 2.
        engine: The exact engine; variable elimination by default.

    Returns:
        The findings, grouped by diagnostic in the order above; ``[f.to_dict() for f in ...]`` is
        ready for ``json.dumps``.

    Raises:
        ValidationError: If a threshold or ``min_supports`` is out of range, ``target`` or an evidence
            node is not an inference variable, or the evidence observes the target.
        CompileError: If the graph has no missing parameter but still fails to compile, for example
            over conflicting bases on merged nodes.
        ZeroProbabilityError: If the evidence and the ``exclusive`` constraints have probability zero.
    """
    report = diagnose_many(
        graph,
        () if target is None else (target,),
        evidence=evidence,
        claim_threshold=claim_threshold,
        failure_threshold=failure_threshold,
        min_supports=min_supports,
        engine=engine,
    )
    return report.all_findings()

def diagnose_many(  # noqa: PLR0913 - the options after the targets are keyword-only
    graph: Graph,
    targets: Iterable[str],
    *,
    evidence: Mapping[str, bool] | None = None,
    claim_threshold: float = DEFAULT_CLAIM_THRESHOLD,
    failure_threshold: float = DEFAULT_FAILURE_THRESHOLD,
    min_supports: int = DEFAULT_MIN_SUPPORTS,
    engine: Engine | None = None,
) -> Report:
    """Run the graph-wide diagnostics once and the weak-point diagnostics for each of several targets.

    The graph-wide findings are those ``diagnose`` reports without a target; each target's weak
    points are those ``diagnose`` adds for it, under the same evidence and thresholds. A target named
    twice is diagnosed once. If a parameter is missing the graph cannot be compiled, and every
    target's list is empty.

    Args:
        graph: The graph.
        targets: The ids of the nodes whose weak points are wanted; may be empty.
        evidence: Node ids and their observed values; none by default.
        claim_threshold: The threshold passed to ``claims``, a gap in natural log-odds.
        failure_threshold: The threshold passed to ``single_points_of_failure``, a fraction of each
            target's own probability.
        min_supports: The smallest group passed to ``correlated_support``, at least 2.
        engine: The exact engine; variable elimination by default.

    Returns:
        The graph-wide findings, and each target's weak points in the order the targets were given;
        ``report.to_dicts()`` is ready for ``json.dumps``.

    Raises:
        ValidationError: If ``targets`` is a single string, a threshold or ``min_supports`` is out of
            range, a target or an evidence node is not an inference variable, or the evidence observes
            a target.
        CompileError: If the graph has no missing parameter but still fails to compile, for example
            over conflicting bases on merged nodes.
        ZeroProbabilityError: If the evidence and the ``exclusive`` constraints have probability zero.
    """
    if isinstance(targets, str):
        msg = f"targets must be a collection of node ids, not the string {targets!r}"
        raise ValidationError(msg)
    targets = list(dict.fromkeys(targets))
    findings = missing_parameters(graph)
    structural = [*unanchored(graph), *correlated_support(graph, min_supports)]
    if findings:
        return Report((*findings, *structural), dict.fromkeys(targets, ()))
    findings.extend(structural)
    engine = engine or VariableElimination()
    network = compile_graph(graph)
    findings.extend(claims(graph, network, evidence=evidence, threshold=claim_threshold, engine=engine))
    weak_points: dict[str, list[Finding]] = {}
    for target in targets:
        slopes = derivatives(network, target, evidence=evidence, engine=engine)
        found = weak_points[target] = []
        found.extend(sensitivity_findings(network, target, slopes, evidence=evidence))
        found.extend(crux_findings(network, target, slopes, evidence=evidence))
        run = interventions(network, target, evidence=evidence, threshold=failure_threshold, engine=engine)
        found.extend(single_point_of_failure_findings(run))
        found.extend(failure_impact_findings(run))
        found.extend(value_of_information(network, target, evidence=evidence, engine=engine))
    return Report(findings, weak_points)

def failure_impact(
    network: Network,
    target: str,
    *,
    evidence: Mapping[str, bool] | None = None,
    threshold: float = DEFAULT_FAILURE_THRESHOLD,
    engine: Engine | None = None,
) -> list[Finding]:
    """Rank the other variables Y by ``P(target | do(Y = false), evidence) / P(target | evidence)``.

    The ratio is the fraction of the target's probability that survives the failure of Y, with the
    intervention of ``single_points_of_failure``: below 1 the failure lowers the target, above 1 it
    raises it. Every candidate of ``single_points_of_failure`` is ranked, lowest ratio first, and the
    threshold only marks the line: a finding whose ratio falls below it, under the same rounding
    rule, is exactly one ``single_points_of_failure`` reports. The ranking therefore orders the
    premises by failure impact without a second run at another threshold, which matters because a
    premise behind one ``requires`` of strength r keeps at least ``1 - r`` of the target and crosses
    the default line only for r > 0.9; see ``single_points_of_failure``.

    Args:
        network: The network.
        target: The id of the target node.
        evidence: Node ids and their observed values; none by default.
        threshold: The fraction of ``P(target | evidence)`` that marks a single point of failure, as
            for ``single_points_of_failure``; it does not filter the ranking.
        engine: The exact engine; variable elimination by default.

    Returns:
        One finding per candidate, lowest ratio first, ties in network order; its value is the ratio,
        and its details give ``P(target | evidence)`` as ``baseline``,
        ``P(target | do(Y = false), evidence)`` as ``p_target_if_false``, the fraction as
        ``threshold``, and ``single_point_of_failure``, true for a ratio below the threshold. When
        ``P(target | evidence)`` is zero there is nothing to lose and the ratio is undefined, so
        there are no findings.

    Raises:
        ValidationError: If ``threshold`` is not in [0, 1], ``target`` or an evidence node is not an
            inference variable, or the evidence observes the target.
        ZeroProbabilityError: If the evidence and the ``exclusive`` constraints have probability zero,
            or the constraints alone do under one of the interventions.
    """
    run = interventions(network, target, evidence=evidence, threshold=threshold, engine=engine)
    return failure_impact_findings(run)

def missing_parameters(graph: Graph) -> list[Finding]:
    """Find inference variables without a ``base`` and inferential relations without a ``strength``.

    Nodes merged by ``equivalent`` relations form one variable, which needs a base on at least one of
    them. A graph with any such finding cannot be compiled: there is no default credence.

    ``Relation`` already refuses to be built without a strength when its type needs one, so the
    second check only fires on a graph whose relations were altered after validation.

    Args:
        graph: The graph.

    Returns:
        One finding per variable without a base, then one per relation without a strength.
    """
    findings: list[Finding] = []
    for root, ids in inference_sets(graph).items():
        if any(graph.nodes[node_id].base is not None for node_id in ids):
            continue
        findings.append(
            Finding(
                id=f"{MISSING_PARAMETER}:base:{root}",
                diagnostic=MISSING_PARAMETER,
                message=f"node {_describe(ids)} is an inference variable without a base; there is no default credence",
                nodes=tuple(ids),
            )
        )
    for relation in graph.relations.values():
        if relation.type in STRENGTH_TYPES and relation.strength is None:
            findings.append(
                Finding(
                    id=f"{MISSING_PARAMETER}:strength:{relation.id}",
                    diagnostic=MISSING_PARAMETER,
                    message=f"{relation.type} relation {relation.id!r} has no strength",
                    nodes=(relation.source, relation.target),
                    relations=(relation.id,),
                )
            )
    return findings

def sensitivity(
    network: Network,
    target: str,
    *,
    evidence: Mapping[str, bool] | None = None,
    engine: Engine | None = None,
) -> list[Finding]:
    """Report ``dP(target | evidence)/dθ`` for every parameter θ.

    Args:
        network: The network.
        target: The id of the target node.
        evidence: Node ids and their observed values; none by default.
        engine: The exact engine; variable elimination by default.

    Returns:
        One finding per parameter, largest magnitude first; its value is the signed derivative.

    Raises:
        ValidationError: If ``target`` or an evidence node is not an inference variable of the
            network, or the evidence observes the target.
        ZeroProbabilityError: If the evidence and the ``exclusive`` constraints have probability zero.
    """
    slopes = derivatives(network, target, evidence=evidence, engine=engine)
    return sensitivity_findings(network, target, slopes, evidence=evidence)

def single_points_of_failure(
    network: Network,
    target: str,
    *,
    evidence: Mapping[str, bool] | None = None,
    threshold: float = DEFAULT_FAILURE_THRESHOLD,
    engine: Engine | None = None,
) -> list[Finding]:
    """Find the variables Y whose failure alone sinks the target: ``P(target | do(Y = false), evidence)``.

    The intervention cuts the relations into Y and fixes it false, as in "suppose this premise is
    simply wrong"; the evidence is then conditioned on. A variable is reported when that probability
    is below ``threshold * P(target | evidence)``: the threshold is a fraction of the target's own
    probability, not a probability, so the same default separates the premises that sink the target
    from those that merely dent it whether the target starts at 0.9 or at 0.01. A threshold of 1
    reports every variable whose failure lowers the target at all; 0 reports none.

    **A premise behind one ``requires`` of strength r is reported only if r > 1 - threshold.** Let
    the only directed path from Y to T be one ``requires`` relation Y -> T of strength r, with no
    evidence and no ``exclusive`` constraint. ``P(T = 1 | parents)`` is Y's necessity gate, 1 - r
    when Y is false and 1 when it is true, times a factor A that does not involve Y. Failing Y leaves
    the distribution of T's other parents as it was, so ``P(T | do(Y = false)) = (1 - r) E[A]``,
    while ``P(T) <= E[A]`` because the gate is at most 1. Hence

        P(T | do(Y = false)) / P(T) >= 1 - r,

    and when Y shares no ancestor with T's other parents the ratio is exactly
    ``(1 - r) / ((1 - r) + r p)`` with ``p = P(Y)``, which tends to 1 - r as p tends to 1. At the
    default threshold of 0.1 such a premise is never reported when r <= 0.9, however probable it is:
    an empty list then says that no ``requires`` is stronger than 0.9, not that nothing is fatal.
    ``failure_impact`` ranks every candidate by the same ratio, so the premises that dent the target
    most are visible whether or not one crosses the line.

    Observed variables are not candidates: the evidence already says whether they hold. Nor is a
    variable whose failure the evidence rules out, where ``P(evidence | do(Y = false))`` is zero:
    given what was observed, Y did not fail.

    Args:
        network: The network.
        target: The id of the target node.
        evidence: Node ids and their observed values; none by default.
        threshold: The fraction of ``P(target | evidence)`` below which the target counts as failed;
            a probability within a relative 1e-12 of the cutoff counts as equal to it, so rounding
            cannot tip a finding however small ``P(target | evidence)`` is. The default, 0.1, an
            order of magnitude, is a convention chosen for this package rather than a value the model
            fixes.
        engine: The exact engine; variable elimination by default.

    Returns:
        One finding per single point of failure, lowest remaining probability first; its value is
        ``P(target | do(Y = false), evidence)``, and its details give ``P(target | evidence)`` as
        ``baseline`` and the fraction as ``threshold``.

    Raises:
        ValidationError: If ``threshold`` is not in [0, 1], ``target`` or an evidence node is not an
            inference variable, or the evidence observes the target.
        ZeroProbabilityError: If the evidence and the ``exclusive`` constraints have probability zero,
            or the constraints alone do under one of the interventions.
    """
    run = interventions(network, target, evidence=evidence, threshold=threshold, engine=engine)
    return single_point_of_failure_findings(run)

def sorries(graph: Graph, target: str, directory: str | Path, *, engine: Engine | None = None) -> SorryReport:
    """Report the steps a target depends on that remain sorries, ranked by the target's sensitivity.

    Each sorry with a strength is ranked by ``dP(target)/d strength``, taken exactly as in
    ``derivatives`` with every parameter at its credence mean. A discharged step is not ranked:
    credence applies only to what remains unproven.

    Args:
        graph: The graph, which must compile for inference.
        target: The target node's id.
        directory: The directory script paths are relative to.
        engine: The exact engine; variable elimination by default.

    Returns:
        The report.

    Raises:
        CompileError: If the graph cannot be compiled.
        ValidationError: If ``target`` is not an inference variable.
        ZeroProbabilityError: If no world satisfies the ``exclusive`` constraints.
    """
    slopes = derivatives(compile_graph(graph), target, engine=engine)
    steps = dependencies(graph, target)
    discharged = []
    found = []
    for relation in steps:
        reason = sorry_reason(relation, directory)
        if reason is None:
            discharged.append(relation.id)
            continue
        found.append(
            Sorry(
                relation.id,
                relation.type,
                relation.source,
                relation.target,
                reason,
                relation.obligation and relation.obligation.statement,
                slopes.get(ParameterKey("strength", relation.id)),
            )
        )
    found.sort(key=lambda sorry: (sorry.sensitivity is None, -abs(sorry.sensitivity or 0.0)))
    return SorryReport(target, tuple(relation.id for relation in steps), tuple(discharged), tuple(found))

def unanchored(graph: Graph) -> list[Finding]:
    """Find inference variables with no source and no inferential parents.

    Such a variable is an assumption nobody wrote down: nothing in the graph says where its credence
    comes from. Nodes merged by ``equivalent`` relations are one variable, anchored if any of them
    has a source or is the target of a ``requires``, ``supports`` or ``refutes`` relation.

    Args:
        graph: The graph.

    Returns:
        One finding per unanchored variable, in insertion order.
    """
    has_parents = {relation.target for relation in graph.relations.values() if relation.type in STRENGTH_TYPES}
    findings: list[Finding] = []
    for root, ids in inference_sets(graph).items():
        if any(graph.nodes[node_id].sources or node_id in has_parents for node_id in ids):
            continue
        findings.append(
            Finding(
                id=f"{UNANCHORED}:{root}",
                diagnostic=UNANCHORED,
                message=f"node {_describe(ids)} has no source and no inferential parents: an assumption nobody wrote down",
                nodes=tuple(ids),
            )
        )
    return findings

def value_of_information(
    network: Network,
    target: str,
    *,
    evidence: Mapping[str, bool] | None = None,
    engine: Engine | None = None,
) -> list[Finding]:
    """Rank the other variables Y by the mutual information ``I(target; Y | evidence)``, in bits.

    ``I(T; Y | E)`` is the expected reduction in the entropy of T from learning whether Y is true,
    once E is known, so the top of the ranking is what would most change the target if it were
    resolved next, and is the first thing to investigate. It is at most 1 bit, the entropy of a
    binary variable. Observed variables are left out: learning them again tells nothing.

    The unit, bits (logarithms to base 2), is a choice of this package; the ranking does not depend
    on it. Multiply by ``ln 2`` for nats.

    Args:
        network: The network.
        target: The id of the target node.
        evidence: Node ids and their observed values; none by default.
        engine: The exact engine; variable elimination by default.

    Returns:
        One finding per other unobserved proposition variable, most informative first. Its details
        give ``P(target | evidence)`` as ``p_target`` and, for each value of Y with positive
        probability, ``P(target | Y, evidence)`` as ``p_target_given_true`` or ``_false``.

    Raises:
        ValidationError: If ``target`` or an evidence node is not an inference variable of the
            network, or the evidence observes the target.
        ZeroProbabilityError: If the evidence and the ``exclusive`` constraints have probability zero.
    """
    engine = engine or VariableElimination()
    given = _observed(network, target, evidence).evidence
    findings = []
    for name, members in _others(network, target, given):
        table = [
            [engine.query(network, Query({target: bool(t), name: bool(y)}, given)) for y in (0, 1)] for t in (0, 1)
        ]
        bits = _mutual_information(table)
        details = {"p_target": table[1][0] + table[1][1]}
        for y, label in ((1, "true"), (0, "false")):
            p_y = table[0][y] + table[1][y]
            if p_y > 0.0:
                details[f"p_target_given_{label}"] = table[1][y] / p_y
        findings.append(
            Finding(
                id=f"{VALUE_OF_INFORMATION}:{name}",
                diagnostic=VALUE_OF_INFORMATION,
                message=(
                    f"learning whether {name!r} is true would give {bits:.3g} bits of information about "
                    f"{target!r}{' given ' + render_evidence(given) if given else ''}"
                ),
                nodes=members,
                value=bits,
                details=details,
            )
        )
    return sorted(findings, key=lambda finding: -(finding.value or 0.0))