Skip to content

ontocast.agent.convert_document

Document conversion agent for OntoCast.

This module provides functionality for converting various document formats into structured data that can be processed by the OntoCast system.

Attributes

logger = logging.getLogger(__name__) module-attribute

Classes

Functions:

convert_document(state, tools)

Convert the state's input document into a DoclingDocument.

One state is one document; a caller with several (a batch request, JSONL lines) builds one state per document before this node runs. A state that already carries docling_doc is not converted again: the document is kept and only its hash (doc_hid) is set, so a document kept from an earlier run is chunked and namespaced exactly as that run was.

Parameters:

Name Type Description Default
state AgentState

The current agent state, carrying input_document.

required
tools ToolBox

The toolbox instance providing utility functions.

required

Returns:

Name Type Description
AgentState AgentState

Updated state with docling_doc populated, or with

AgentState

status == Status.FAILED if conversion could not be performed.

Source code in ontocast/agent/convert_document.py
def convert_document(state: AgentState, tools: ToolBox) -> AgentState:
    """Convert the state's input document into a DoclingDocument.

    One state is one document; a caller with several (a batch request, JSONL
    lines) builds one state per document before this node runs. A state that
    already carries ``docling_doc`` is not converted again: the document is
    kept and only its hash (``doc_hid``) is set, so a document kept from an
    earlier run is chunked and namespaced exactly as that run was.

    Args:
        state: The current agent state, carrying ``input_document``.
        tools: The toolbox instance providing utility functions.

    Returns:
        AgentState: Updated state with ``docling_doc`` populated, or with
        ``status == Status.FAILED`` if conversion could not be performed.
    """
    logger.debug("Converting document")

    state.status = Status.SUCCESS
    if state.docling_doc is not None:
        # Converted by the caller (e.g. kept from an earlier run): the same
        # document gives the same hash, so the same namespace and entity IRIs.
        state.set_docling_doc(state.docling_doc)
        blocked = _fail_when_fixed_catalog_ontology_missing(state)
        return blocked if blocked is not None else state

    if state.input_document is None:
        logger.error("convert_document needs an input document; the state has none")
        state.status = Status.FAILED
        return state

    filename = state.input_document.filename
    file_content = state.input_document.data
    file_extension = pathlib.Path(filename).suffix.lower()
    logger.debug("Converting %s with extension %s", filename, file_extension)

    if file_extension in tools.converter.supported_extensions:
        doc = tools.converter(file_content, filename=filename)
        state.set_docling_doc(doc)
        blocked = _fail_when_fixed_catalog_ontology_missing(state)
        return blocked if blocked is not None else state

    if file_extension == ".json":
        result_json = json.loads(file_content.decode("utf-8"))
        json_text = _extract_json_payload_text(result_json, state, filename)
        if json_text is None:
            state.status = Status.FAILED
            return state
        state.set_docling_doc(plain_text_to_docling_doc(json_text, filename))
        blocked = _fail_when_fixed_catalog_ontology_missing(state)
        return blocked if blocked is not None else state

    if file_extension == ".txt":
        text = file_content.decode("utf-8")
        state.set_docling_doc(plain_text_to_docling_doc(text, filename))
        blocked = _fail_when_fixed_catalog_ontology_missing(state)
        return blocked if blocked is not None else state

    logger.error("Unsupported file extension %s for %s", file_extension, filename)
    accepted = sorted({*tools.converter.supported_extensions, ".json", ".txt"})
    state.set_failure(
        FailureStage.UNSUPPORTED_DOCUMENT,
        f"{filename} is not a supported file type. Accepted: {', '.join(accepted)}. "
        "PDF, Office, HTML, Markdown and image files need the `doc-processing` extra.",
    )
    return state