Assembler

def assemble(graph: Graph, rubric: Rubric, records: Sequence[Any]) -> Assembly:
    """Apply classify records in document order through the core's ``split`` and ``annotate``.

    Each record is applied as a whole or not at all. One is rejected, and its node left as it was,
    when it is malformed, names a node the graph lacks or one that is not a document chunk, repeats
    the node of an earlier record, or the core refuses one of its edits: an
    unknown type, a form not found in the text, a clause that does not occur exactly once, a
    rests-on node of a type the edge rule does not allow. A hedge phrase that is not a substring of
    its node's text rejects the record too. One the text contains sets ``Node.stated`` to the
    rubric's credence for it, or, if ``[hedges]`` does not list it, is returned as unmapped.

    Args:
        graph: The graph, left unchanged.
        rubric: The rubric.
        records: The records, as the model returned them.

    Returns:
        The graph, the rejections and the unmapped hedge phrases.
    """
    graph, rejections, unmapped = _apply_all(
        graph, records, "node", _admit_chunk, lambda graph, record: _apply(graph, rubric, record)
    )
    return Assembly(graph, rejections, unmapped)

def assemble_premises(graph: Graph, rubric: Rubric, records: Sequence[Any]) -> PremiseAssembly:
    """Apply premise records in document order of their conclusions.

    Each record is applied as a whole or not at all. One is rejected, and its conclusion left as it
    was, when it is malformed, names a node the graph lacks or one that is not a document node of a
    type in ``premises.for``, repeats the conclusion of an earlier record, or
    the core refuses a ``stated_at`` link: a node of a type the edge rule does not allow, a relation
    that already exists or would close a cycle. A conclusion takes at most
    ``premises.max_per_conclusion`` analyst premises; the statements beyond are returned as overflow,
    not added. A statement repeated within one record is one premise.

    Args:
        graph: The graph, left unchanged.
        rubric: The rubric; it must pass ``premises_rubric_problem``.
        records: The records, as the model returned them.

    Returns:
        The graph, the rejections and the overflow.

    Raises:
        ValueError: If the rubric cannot take premise records.
    """
    problem = premises_rubric_problem(rubric)
    if problem is not None:
        raise ValueError(problem)
    for_types = rubric.premises.for_types  # type: ignore[union-attr]

    def admit(node: Node) -> None:
        if origin_of(node) != DOCUMENT or node.kind not in for_types:
            msg = f"node {node.id!r} is a {node.kind!r}, not a conclusion of a type in premises.for {list(for_types)}"
            raise _RecordError(INVALID_RECORD, msg)

    graph, rejections, overflow = _apply_all(
        graph, records, "conclusion", admit, lambda graph, record: _apply_premises(graph, rubric, record)
    )
    return PremiseAssembly(graph, rejections, overflow)

def edge_rules_not_requires(rubric: Rubric) -> list[str]:
    """Return the types whose edge rule creates a relation other than ``requires``.

    Text may only add ``requires`` relations: with no other parents, a node's credence cannot exceed
    its type's base, whatever the text says. A ``supports`` edge rule would let a document raise the
    credence of its own claims, so a rubric with one cannot be used for extraction.

    Args:
        rubric: The rubric.

    Returns:
        The names of those types, in declaration order.
    """
    return [
        name for name, spec in rubric.types.items() if spec.rests_on is not None and spec.rests_on.relation != REQUIRES
    ]

def fixes(graph: Graph, rubric: Rubric, record: Any) -> list[str]:
    """Say what to change in a classify record so the assembler can apply it, as instructions to the model.

    The record is read against the graph it was applied to and the rubric, independently of the error the
    core gave: a node id that is not a chunk (and, for an id such as ``s-2a``, how a chunk is split), a type
    a chunk may not have, ``rests_on`` on a type that rests on nothing or naming nodes of other types, form
    fields of another type, a required one missing, a value or hedge not found in the text, and a clause
    that does not occur exactly once.

    Args:
        graph: The graph the record was applied to.
        rubric: The rubric.
        record: The record, as the model returned it.

    Returns:
        One instruction per problem found, in the record's order; empty when none is found.
    """
    if not isinstance(record, Mapping):
        return ["send each record as a JSON object"]
    node_fix = _node_fix(graph, record.get("node"))
    if node_fix is not None:
        return [node_fix]
    node_id = record["node"]
    text = node_text(graph, graph.nodes[node_id])
    if "split" not in record:
        return _part_fixes(graph, rubric, record, text=text)
    clauses, children = record.get("split"), record.get("children")
    if not isinstance(clauses, list) or not isinstance(children, list) or len(clauses) != len(children):
        return ['a split record needs "split", a list of clauses, and "children", one typed record per clause']
    out = []
    for i, (clause, child) in enumerate(zip(clauses, children, strict=True)):
        found = text.count(clause) if isinstance(clause, str) and clause else 0
        if found != 1:
            out.append(
                f"clause {i + 1} occurs {found} times in the text of {node_id!r}: copy a clause that occurs once"
            )
        clause_text = clause if isinstance(clause, str) else ""
        found = _part_fixes(graph, rubric, child, text=clause_text, where="the clause's text")
        out.extend(f"children[{i}]: {fix}" for fix in found)
    return out

def premises_rubric_problem(rubric: Rubric) -> str | None:
    """Say why a rubric cannot take premise records, or return ``None`` if it can.

    Args:
        rubric: The rubric.

    Returns:
        The problem: the rubric has no ``[premises]`` table, or does not declare the ``assumption``
        type for analyst nodes.
    """
    if rubric.premises is None:
        return f"rubric {rubric.name!r} has no [premises] table"
    spec = rubric.types.get(ASSUMPTION)
    if spec is None or ANALYST not in spec.origins:
        return f"rubric {rubric.name!r} does not declare the type {ASSUMPTION!r} with origin {ANALYST!r}"
    return None

def unlabelled(value: Any) -> str | None:
    """Return the id a model wrote with the label a listing shows it with, as ``s-2`` of ``s-2 (result)``.

    Args:
        value: What the model wrote where an id belongs.

    Returns:
        The id before the label, or ``None`` when ``value`` is not an id followed by a label.
    """
    match = _LABELLED.fullmatch(value) if isinstance(value, str) else None
    return match[1] if match else None