Graph tools

def add_premises(
    run: Path, records: Sequence[Any], *, model: str, agent: str | None = None, note: str | None = None
) -> dict[str, Any]:
    """Add the implicit premises of conclusions.

    Args:
        run: The run directory.
        records: Premise records, each ``{"conclusion", "premises": [{"stated_at"} | {"statement"}, ...]}``.
        model: The model making the call, as the harness reports it.
        agent: A name for the agent.
        note: Free text kept with the call.

    Returns:
        ``applied``, the nodes created or changed (analyst premises included); ``refused``, each
        refused record with its code and message; and ``overflow``, premises beyond the rubric's limit.

    Raises:
        RunError: If the rubric takes no premises, or the call as a whole is refused.
    """
    return write(run, ADD_PREMISES, {"records": _sent(records)}, model=model, agent=agent, note=note)

def checked(graph: Graph) -> set[str]:
    """Return the nodes a check targets: the sources of ``observes`` relations.

    Args:
        graph: The graph.

    Returns:
        Their ids.
    """
    return {relation.source for relation in graph.relations.values() if relation.type == OBSERVES}

def classify(
    run: Path, records: Sequence[Any], *, model: str, agent: str | None = None, note: str | None = None
) -> dict[str, Any]:
    """Type, split and link chunks of a run's document.

    Args:
        run: The run directory.
        records: Classify records, each ``{"node", "type", "form"?, "rests_on"?, "hedge"?}`` or
            ``{"node", "split", "children"}``.
        model: The model making the call, as the harness reports it.
        agent: A name for the agent, for runs with several.
        note: Free text kept with the call, never used in inference.

    Returns:
        ``applied``, the nodes created or changed; ``refused``, each refused record with its code,
        message and ``fix``; and ``unmapped_hedges``, hedge phrases the rubric does not list.

    Raises:
        RunError: If the call as a whole is refused (``records`` not a list, the run busy or malformed).
    """
    return write(run, CLASSIFY, {"records": _sent(records)}, model=model, agent=agent, note=note)

def finish_run(run: Path, *, model: str, agent: str | None = None, note: str | None = None) -> dict[str, Any]:
    """Derive the verdicts, check the graph with the core, and write the run's outputs.

    It may be called again after later writes, which mark the run unfinished.

    Args:
        run: The run directory.
        model: The model making the call, as the harness reports it.
        agent: A name for the agent.
        note: Free text kept with the call.

    Returns:
        ``findings``, every violation the core's check reports at the ``assessed`` level with rubric
        credences, and ``ok``, whether there are none.
    """
    return write(run, FINISH, {}, model=model, agent=agent, note=note)

def judge_citation(  # noqa: PLR0913 - the check, what the agent judged, and who makes the call
    run: Path,
    target: str,
    reference: str,
    source: str,
    passage: str,
    *,
    supports: bool,
    model: str,
    agent: str | None = None,
    note: str | None = None,
    fetcher: Callable[[str], Any] = fetch,
) -> dict[str, Any]:
    """Record a citation check: read the source, find the passage, and decide whether the source is tied to the reference.

    The tool reads the source itself; it never takes the text from the agent. A local source is a file
    of the run's copy of the cited works; a URL is fetched under the fetch policy (``fetch``). What was
    read (the file or URLs, the digests of the bytes and of their text, where the passage is, and what
    ties the source to the reference) is logged with the call, not the bytes, which are kept in
    ``sources/`` only when the run stores its sources. The check passes or fails, as the agent judged,
    only when the passage is in the source and the source is tied to the reference
    (``citation.tie``); otherwise it is an ``error``, which moves no credence. A target whose citation
    check passed or failed takes no other; one whose checks erred may be checked again.

    Args:
        run: The run directory.
        target: The citing node.
        reference: The id of the bibliography entry (``r-N``), not its key.
        source: A file of the run's cited works, by name or path, or an ``http`` or ``https`` URL.
        passage: The passage of the source the target rests on, verbatim.
        supports: Whether the passage supports the target.
        model: The model making the call, as the harness reports it.
        agent: A name for the agent.
        note: Free text kept with the call.
        fetcher: Fetches a URL under the fetch policy; ``fetch.fetch`` by default.

    Returns:
        ``check``, the id of the check, ``result``, ``tied`` and ``detail``; or ``check`` ``None`` and
        ``refused``, with the refusal's code, message and ``fix``.

    Raises:
        RunError: If an argument is not of its type, or the call as a whole is refused.
    """
    args = {
        "target": target,
        "reference": reference,
        "source": source,
        "passage": passage,
        "supports": supports,
        "read": _observe(run, reference, source, passage, fetcher),
        "versions": versions(),
    }
    return write(run, JUDGE_CITATION, args, model=model, agent=agent, note=note)

def run_checks(
    run: Path, proposals: Sequence[Any], *, model: str, agent: str | None = None, note: str | None = None
) -> dict[str, Any]:
    """Check and run proposals of the maths check types: ``recompute-numbers`` and ``rederive-maths``.

    A check, once run, is part of the run: it cannot be withdrawn or run again on the same target, nor
    run again on another target in another encoding of the same step. The versions of the code that
    runs the checks are recorded with the call.

    Args:
        run: The run directory.
        proposals: Check proposals, each ``{"target", "type": "recompute-numbers", "nodes", "expression",
            "expected"}`` or ``{"target", "type": "rederive-maths", "nodes", "lhs", "rhs", "symbols",
            "assumption"}``.
        model: The model making the call, as the harness reports it.
        agent: A name for the agent.
        note: Free text kept with the call.

    Returns:
        ``checks``, each check run with its id, type, target, result and detail (a ``rederive-maths``
        that errs is followed by its numeric fallback when the rubric declares one); and ``refused``,
        each refused proposal with its code, message and ``fix``.

    Raises:
        RunError: If the call as a whole is refused.
    """
    args = {"proposals": _sent(proposals), "versions": versions()}
    return write(run, RUN_CHECKS, args, model=model, agent=agent, note=note)