ontocast.onto.docling_helpers

Helpers for constructing and normalizing DoclingDocument instances.

docling-core is resolved on demand: it ships in the documents extra, and these helpers sit on the import path of modules the light core does load.

apply_text_sanitizers(doc, *, repair_ligature_gaps_enabled=False)

Apply optional post-conversion text sanitizers to a DoclingDocument.

Source code in ontocast/onto/docling_helpers.py

def apply_text_sanitizers(
    doc: DoclingDocument,
    *,
    repair_ligature_gaps_enabled: bool = False,
) -> DoclingDocument:
    """Apply optional post-conversion text sanitizers to a DoclingDocument."""
    if not repair_ligature_gaps_enabled:
        return doc

    # Works around publisher-PDF ligature splits that Docling passes through.
    # Removable once upstream Docling normalises ASCII fi/fl/ff gap patterns --
    # a breaking change, since the flag is in the converter cache key.
    for item in doc.texts:
        item.text = repair_ligature_gaps(item.text)

    return doc

json_payload_text(payload)

Document text inside a JSON payload, by a small top-level heuristic.

text when present, else the longest top-level string. Lives here rather than in the conversion agent because JSON inputs are routed around the Docling converter entirely -- anything that reads a document from a path has to make the same choice, and two copies of the heuristic would let the CLI and the pipeline disagree about what a file's text even is.

Parameters:

Name	Type	Description	Default
payload	object	Parsed JSON, expected to be an object.	required

Returns:

Type	Description
str | None	The document text, or None when the payload is not an object or
str | None	holds no string.

Source code in ontocast/onto/docling_helpers.py

def json_payload_text(payload: object) -> str | None:
    """Document text inside a JSON payload, by a small top-level heuristic.

    ``text`` when present, else the longest top-level string. Lives here rather
    than in the conversion agent because JSON inputs are routed around the
    Docling converter entirely -- anything that reads a document from a path has
    to make the same choice, and two copies of the heuristic would let the CLI
    and the pipeline disagree about what a file's text even is.

    Args:
        payload: Parsed JSON, expected to be an object.

    Returns:
        The document text, or ``None`` when the payload is not an object or
        holds no string.
    """
    if not isinstance(payload, dict):
        return None
    text_value = payload.get("text")
    if isinstance(text_value, str):
        return text_value

    largest_text: str | None = None
    for value in payload.values():
        if isinstance(value, str):
            if largest_text is None or len(value) > len(largest_text):
                largest_text = value
    return largest_text

plain_text_to_docling_doc(text, doc_name)

Wrap plain text as a single-paragraph DoclingDocument.

Source code in ontocast/onto/docling_helpers.py

def plain_text_to_docling_doc(text: str, doc_name: str) -> DoclingDocument:
    """Wrap plain text as a single-paragraph DoclingDocument."""
    doc_module = require("docling_core.types.doc", feature="Docling documents")
    doc = doc_module.DoclingDocument(name=doc_name)
    doc.add_text(label=doc_module.DocItemLabel.PARAGRAPH, text=text)
    return doc

repair_ligature_gaps(text)

Repair common ASCII ligature gaps in extracted publisher-PDF text.

Source code in ontocast/onto/docling_helpers.py

def repair_ligature_gaps(text: str) -> str:
    """Repair common ASCII ligature gaps in extracted publisher-PDF text."""
    return _LIGATURE_GAP_RE.sub(r"\1", text)