Skip to content

ontocast.agent.resolve_home_ontology

Resolve a document's home ontology: where its new vocabulary is minted.

One LLM call per document, before the ontology fan-out. The model proposes an ontology_id (plus title and description); code decides what that means: an id already in the catalog makes the document extend that ontology, any other id mints a new one under CURRENT_DOMAIN. The model never writes an IRI.

Attributes

logger = logging.getLogger(__name__) module-attribute

Classes

Functions:

identity_for_existing(tools, ontology_id)

The identity of the catalog ontology ontology_id names, if any.

Raises:

Type Description
DivergedOntologyError

that ontology has several heads.

Source code in ontocast/agent/resolve_home_ontology.py
def identity_for_existing(tools: ToolBox, ontology_id: str) -> OntologyIdentity | None:
    """The identity of the catalog ontology ``ontology_id`` names, if any.

    Raises:
        DivergedOntologyError: that ontology has several heads.
    """
    iri = tools.ontology_manager.resolve_ontology_ref(ontology_id)
    if iri is None:
        return None
    head = tools.ontology_manager.get_head_by_iri(iri)
    if head is None:
        return None
    return OntologyIdentity(
        ontology_id=head.ontology_id or ontology_id,
        iri=head.iri,
        title=head.title or head.ontology_id or ontology_id,
        description=head.description or "",
        namespace=head.namespace,
    )

identity_for_new(tools, proposal, current_domain)

A new identity under current_domain, refused if its IRI is taken.

Source code in ontocast/agent/resolve_home_ontology.py
def identity_for_new(
    tools: ToolBox, proposal: OntologyIdentityProposal, current_domain: str
) -> OntologyIdentity:
    """A new identity under ``current_domain``, refused if its IRI is taken."""
    iri = mint_ontology_iri(current_domain, proposal.ontology_id)
    if tools.ontology_manager.resolve_ontology_ref(iri) is not None:
        raise ValueError(
            f"ontology IRI {iri} is already in the catalog under another id"
        )
    return OntologyIdentity(
        ontology_id=proposal.ontology_id,
        iri=iri,
        title=proposal.title,
        description=proposal.description,
    )

propose_home_ontology(state, tools) async

Ask the model for the document's home ontology id, title and description.

Source code in ontocast/agent/resolve_home_ontology.py
async def propose_home_ontology(
    state: AgentState, tools: ToolBox
) -> OntologyIdentityProposal:
    """Ask the model for the document's home ontology id, title and description."""
    heads = tools.ontology_manager.ontologies
    if heads:
        catalog_clause = home_ontology_catalog_clause.format(
            catalog_list="\n".join(
                f"- {o.ontology_id}: {o.title or ''}".rstrip(": ") for o in heads
            )
        )
    else:
        catalog_clause = home_ontology_catalog_clause_empty
    parser = PydanticOutputParser(pydantic_object=OntologyIdentityProposal)
    prompt = PromptTemplate(
        template=_TEMPLATE,
        input_variables=[
            "preamble",
            "instruction",
            "user_instruction",
            "text",
            "format_instructions",
        ],
    )
    record_active_count("llm/ontology_identity")
    with use_budget_tracker(state.budget_tracker):
        llm_tool = await tools.get_llm_tool(state.budget_tracker)
        return await call_llm_with_retry(
            llm_tool=llm_tool,
            phase=LLMPhase.ONTOLOGY_IDENTITY,
            prompt=prompt,
            parser=parser,
            prompt_kwargs={
                "preamble": system_preamble_ontology,
                "instruction": home_ontology_instruction.format(
                    catalog_clause=catalog_clause
                ),
                "user_instruction": state.ontology_user_instruction,
                "text": text_template.format(text=build_document_excerpt(state)),
                "format_instructions": parser.get_format_instructions(),
            },
        )

resolve_home_ontology(state, tools) async

Set state.home_ontology for a run that can create vocabulary.

A facts-only run, or one with no text, gets none. An existing id resolves to that ontology's head; a new id is minted under state.current_domain.

Raises:

Type Description
DivergedOntologyError

the chosen catalog ontology has several heads.

ValueError

the minted IRI is already in the catalog under another id.

Source code in ontocast/agent/resolve_home_ontology.py
async def resolve_home_ontology(state: AgentState, tools: ToolBox) -> AgentState:
    """Set ``state.home_ontology`` for a run that can create vocabulary.

    A facts-only run, or one with no text, gets none. An existing id resolves
    to that ontology's head; a new id is minted under ``state.current_domain``.

    Raises:
        DivergedOntologyError: the chosen catalog ontology has several heads.
        ValueError: the minted IRI is already in the catalog under another id.
    """
    state.home_ontology = None
    if not state.render_ontology or not build_document_excerpt(state).strip():
        return state
    proposal = await propose_home_ontology(state, tools)
    identity = identity_for_existing(tools, proposal.ontology_id)
    if identity is None:
        identity = identity_for_new(tools, proposal, state.current_domain)
        logger.info("Home ontology for this document: new %s", identity.iri)
    else:
        logger.info("Home ontology for this document: existing %s", identity.iri)
    state.home_ontology = identity
    if state.status != Status.FAILED:
        state.status = Status.SUCCESS
    return state