Skip to content

ontocast.agent.consolidate_ontology

Decide every term a document minted, before it is written.

After the ontology fan-out, the merged update holds every term the units minted, the plan's and the candidates (terms a unit minted outside the plan). One structured LLM call per batch of terms returns an action per term (:class:~ontocast.onto.model.OntologyTermAction); the actions are compiled into the update without a model (:mod:ontocast.tool.ontology_validation.consolidate).

Each term is shown with what the decision needs and a unit cannot see: the whole document's other terms, its catalog neighbours, the findings on it, and short excerpts from every unit that minted it.

Attributes

EVIDENCE_PER_TERM = 2 module-attribute

EVIDENCE_WINDOW = 200 module-attribute

TARGETS_PER_REASON = 3 module-attribute

logger = logging.getLogger(__name__) module-attribute

Classes

TermContext

What the consolidation prompt shows about one minted term.

Source code in ontocast/agent/consolidate_ontology.py
class TermContext:
    """What the consolidation prompt shows about one minted term."""

    def __init__(self, iri: str, role: str) -> None:
        self.iri = iri
        self.role = role
        self.status = "planned"
        #: Why the term is up for a decision (``candidate``, ``variant``, ...).
        self.reasons: list[str] = []
        self.label = ""
        self.definition = ""
        self.parents: list[str] = []
        self.nearest: list[tuple[str, str]] = []
        self.findings: list[str] = []
        self.excerpts: list[str] = []

Attributes

definition = '' instance-attribute
excerpts = [] instance-attribute
findings = [] instance-attribute
iri = iri instance-attribute
label = '' instance-attribute
nearest = [] instance-attribute
parents = [] instance-attribute
reasons = [] instance-attribute
role = role instance-attribute
status = 'planned' instance-attribute

Methods:

__init__(iri, role)
Source code in ontocast/agent/consolidate_ontology.py
def __init__(self, iri: str, role: str) -> None:
    self.iri = iri
    self.role = role
    self.status = "planned"
    #: Why the term is up for a decision (``candidate``, ``variant``, ...).
    self.reasons: list[str] = []
    self.label = ""
    self.definition = ""
    self.parents: list[str] = []
    self.nearest: list[tuple[str, str]] = []
    self.findings: list[str] = []
    self.excerpts: list[str] = []

Functions:

build_term_contexts(state, *, carriers, minted, flagged, candidates, findings, term_units, plan)

One context per flagged term, ordered by IRI.

Source code in ontocast/agent/consolidate_ontology.py
def build_term_contexts(
    state: AgentState,
    *,
    carriers: Sequence[RDFGraph],
    minted: Mapping[str, str],
    flagged: Mapping[str, Mapping[str, Sequence[str]]],
    candidates: set[str],
    findings: Sequence[OntologyUnitFinding],
    term_units: Mapping[str, set[int]],
    plan: OntologyPlan | None,
) -> list[TermContext]:
    """One context per flagged term, ordered by IRI."""
    plan_nearest: dict[str, list[tuple[str, str]]] = {}
    for term in plan.terms if plan is not None else []:
        plan_nearest[term.iri] = list(term.nearest)
        plan_nearest[term.local_name.casefold()] = list(term.nearest)
    by_subject: dict[str, list[str]] = {}
    for finding in findings:
        if finding.subject:
            by_subject.setdefault(finding.subject, []).append(
                f"{finding.kind}: {finding.message}"
            )
    contexts: list[TermContext] = []
    for iri in sorted(flagged):
        subject = URIRef(iri)
        context = TermContext(iri, minted[iri])
        context.status = "candidate" if iri in candidates else "planned"
        context.reasons = sorted(flagged[iri])
        context.label = first_label(subject, *carriers) or ""
        context.definition = _definition(subject, carriers)
        context.parents = sorted(
            {
                str(parent)
                for graph in carriers
                for predicate in (RDFS.subClassOf, RDFS.subPropertyOf)
                for parent in graph.objects(subject, predicate)
                if isinstance(parent, URIRef)
            }
        )
        context.nearest = flag_targets(flagged[iri])
        for near in plan_nearest.get(iri) or plan_nearest.get(_local_key(iri)) or []:
            if all(near[0] != known for known, _ in context.nearest):
                context.nearest.append(near)
        context.findings = by_subject.get(iri, [])[:3]
        for unit_index in sorted(term_units.get(iri, set())):
            if len(context.excerpts) >= EVIDENCE_PER_TERM:
                break
            if 0 <= unit_index < len(state.content_units):
                excerpt = _excerpt(
                    state.content_units[unit_index].text,
                    context.label or _local_name(iri),
                )
                if excerpt:
                    context.excerpts.append(excerpt)
        contexts.append(context)
    return contexts

consolidate_terms(state, tools, contexts, *, prefixes, batch_size, other_terms='') async

Ask for an action per term, batch_size terms per call.

Returns:

Type Description
list[OntologyTermAction]

Every action returned, and the number of calls that failed; a failed

int

batch leaves its terms to their defaults.

Source code in ontocast/agent/consolidate_ontology.py
async def consolidate_terms(
    state: AgentState,
    tools: ToolBox,
    contexts: Sequence[TermContext],
    *,
    prefixes: Mapping[str, str],
    batch_size: int,
    other_terms: str = "",
) -> tuple[list[OntologyTermAction], int]:
    """Ask for an action per term, ``batch_size`` terms per call.

    Returns:
        Every action returned, and the number of calls that failed; a failed
        batch leaves its terms to their defaults.
    """
    parser = PydanticOutputParser(pydantic_object=OntologyConsolidationReport)
    prompt = PromptTemplate(
        template=template_prompt,
        input_variables=[
            "preamble",
            "instruction",
            "terms",
            "other_terms",
            "user_instruction",
            "format_instructions",
        ],
    )
    home = state.home_ontology
    instruction = consolidation_instruction.format(
        ontology_id=home.ontology_id if home is not None else "of this document",
        title=home.title if home is not None else "its domain",
    )
    actions: list[OntologyTermAction] = []
    failed = 0
    for start in range(0, len(contexts), max(1, batch_size)):
        batch = contexts[start : start + batch_size]
        blocks = "\n\n".join(format_term_block(context, prefixes) for context in batch)
        record_active_count("llm/ontology_consolidation")
        try:
            with use_budget_tracker(state.budget_tracker):
                llm_tool = await tools.get_llm_tool(state.budget_tracker)
                report = await call_llm_with_retry(
                    llm_tool=llm_tool,
                    phase=LLMPhase.ONTOLOGY_CONSOLIDATION,
                    prompt=prompt,
                    parser=parser,
                    prompt_kwargs={
                        "preamble": system_preamble_ontology,
                        "instruction": instruction,
                        "terms": terms_intro.format(term_blocks=blocks),
                        "other_terms": other_terms,
                        "user_instruction": state.ontology_user_instruction,
                        "format_instructions": parser.get_format_instructions(),
                    },
                )
        except RUN_STOPPING_ERRORS:
            raise
        except Exception as exc:  # noqa: BLE001 - the batch keeps its defaults
            logger.warning("Ontology consolidation call failed: %s", exc)
            failed += 1
            continue
        actions.extend(report.actions)
    return actions, failed

flag_targets(reasons)

The terms a term's flags point at, each with what relates them.

Source code in ontocast/agent/consolidate_ontology.py
def flag_targets(
    reasons: Mapping[str, Sequence[str]],
) -> list[tuple[str, str]]:
    """The terms a term's flags point at, each with what relates them."""
    found: list[tuple[str, str]] = []
    for reason in sorted(reasons):
        note = _TARGET_NOTES.get(reason, reason)
        for target in list(reasons[reason])[:TARGETS_PER_REASON]:
            if all(target != iri for iri, _ in found):
                found.append((target, note))
    return found

format_other_terms(minted, flagged, carriers, prefixes)

One line per minted term that needs no decision: possible merge targets.

Source code in ontocast/agent/consolidate_ontology.py
def format_other_terms(
    minted: Mapping[str, str],
    flagged: Mapping[str, object],
    carriers: Sequence[RDFGraph],
    prefixes: Mapping[str, str],
) -> str:
    """One line per minted term that needs no decision: possible merge targets."""
    lines = [
        f"- `{compact_iri(iri, prefixes)}` | {minted[iri]} | "
        f"{first_label(URIRef(iri), *carriers) or ''}".rstrip(" |")
        for iri in sorted(minted)
        if iri not in flagged
    ]
    if not lines:
        return ""
    return other_terms_intro.format(term_lines="\n".join(lines))

format_term_block(context, prefixes)

The prompt lines for one term.

Source code in ontocast/agent/consolidate_ontology.py
def format_term_block(context: TermContext, prefixes: Mapping[str, str]) -> str:
    """The prompt lines for one term."""

    def curie(iri: str) -> str:
        return compact_iri(iri, prefixes)

    lines = [f"### `{curie(context.iri)}` ({context.role}, {context.status})"]
    if context.reasons:
        lines.append("review because: " + ", ".join(context.reasons))
    if context.label:
        lines.append(f"label: {context.label}")
    if context.definition:
        lines.append(f"definition: {context.definition}")
    if context.parents:
        lines.append("parents: " + ", ".join(f"`{curie(p)}`" for p in context.parents))
    if context.nearest:
        lines.append(
            "near: "
            + ", ".join(
                f"`{curie(iri)}`" + (f" ({label})" if label else "")
                for iri, label in context.nearest
            )
        )
    for finding in context.findings:
        lines.append(f"check: {finding}")
    for excerpt in context.excerpts:
        lines.append(f"text: {excerpt}")
    return "\n".join(lines)