docling 2.54.0__py3-none-any.whl → 2.55.0__py3-none-any.whl

docling/backend/xml/jats_backend.py

@@ -2,9 +2,9 @@ import logging
 import traceback
 from io import BytesIO
 from pathlib import Path
-from typing import Final, Optional, Union
+from typing import Final, Optional, Union, cast
 
-from bs4 import BeautifulSoup, Tag
+from bs4 import BeautifulSoup, NavigableString, Tag
 from docling_core.types.doc import (
     DocItemLabel,
     DoclingDocument,
@@ -12,6 +12,8 @@ from docling_core.types.doc import (
     GroupItem,
     GroupLabel,
     NodeItem,
+    TableCell,
+    TableData,
     TextItem,
 )
 from lxml import etree
@@ -350,7 +352,7 @@ class JatsDocumentBackend(DeclarativeDocumentBackend):
 
         return
 
-    def _parse_element_citation(self, node: etree._Element) -> str:  # noqa: C901
+    def _parse_element_citation(self, node: etree._Element) -> str:
         citation: Citation = {
             "author_names": "",
             "title": "",
@@ -535,6 +537,110 @@ class JatsDocumentBackend(DeclarativeDocumentBackend):
 
         return
 
+    @staticmethod
+    def parse_table_data(element: Tag) -> Optional[TableData]:
+        # TODO, see how to implement proper support for rich tables from HTML backend
+        nested_tables = element.find("table")
+        if nested_tables is not None:
+            _log.debug("Skipping nested table.")
+            return None
+
+        # Find the number of rows and columns (taking into account spans)
+        num_rows = 0
+        num_cols = 0
+        for row in element("tr"):
+            col_count = 0
+            is_row_header = True
+            if not isinstance(row, Tag):
+                continue
+            for cell in row(["td", "th"]):
+                if not isinstance(row, Tag):
+                    continue
+                cell_tag = cast(Tag, cell)
+                col_span, row_span = HTMLDocumentBackend._get_cell_spans(cell_tag)
+                col_count += col_span
+                if cell_tag.name == "td" or row_span == 1:
+                    is_row_header = False
+            num_cols = max(num_cols, col_count)
+            if not is_row_header:
+                num_rows += 1
+
+        _log.debug(f"The table has {num_rows} rows and {num_cols} cols.")
+
+        grid: list = [[None for _ in range(num_cols)] for _ in range(num_rows)]
+
+        data = TableData(num_rows=num_rows, num_cols=num_cols, table_cells=[])
+
+        # Iterate over the rows in the table
+        start_row_span = 0
+        row_idx = -1
+        for row in element("tr"):
+            if not isinstance(row, Tag):
+                continue
+
+            # For each row, find all the column cells (both <td> and <th>)
+            cells = row(["td", "th"])
+
+            # Check if cell is in a column header or row header
+            col_header = True
+            row_header = True
+            for html_cell in cells:
+                if isinstance(html_cell, Tag):
+                    _, row_span = HTMLDocumentBackend._get_cell_spans(html_cell)
+                    if html_cell.name == "td":
+                        col_header = False
+                        row_header = False
+                    elif row_span == 1:
+                        row_header = False
+            if not row_header:
+                row_idx += 1
+                start_row_span = 0
+            else:
+                start_row_span += 1
+
+            # Extract the text content of each cell
+            col_idx = 0
+            for html_cell in cells:
+                if not isinstance(html_cell, Tag):
+                    continue
+
+                # extract inline formulas
+                for formula in html_cell("inline-formula"):
+                    math_parts = formula.text.split("$$")
+                    if len(math_parts) == 3:
+                        math_formula = f"$${math_parts[1]}$$"
+                        formula.replace_with(NavigableString(math_formula))
+
+                # TODO: extract content correctly from table-cells with lists
+                text = HTMLDocumentBackend.get_text(html_cell).strip()
+                col_span, row_span = HTMLDocumentBackend._get_cell_spans(html_cell)
+                if row_header:
+                    row_span -= 1
+                while (
+                    col_idx < num_cols
+                    and grid[row_idx + start_row_span][col_idx] is not None
+                ):
+                    col_idx += 1
+                for r in range(start_row_span, start_row_span + row_span):
+                    for c in range(col_span):
+                        if row_idx + r < num_rows and col_idx + c < num_cols:
+                            grid[row_idx + r][col_idx + c] = text
+
+                table_cell = TableCell(
+                    text=text,
+                    row_span=row_span,
+                    col_span=col_span,
+                    start_row_offset_idx=start_row_span + row_idx,
+                    end_row_offset_idx=start_row_span + row_idx + row_span,
+                    start_col_offset_idx=col_idx,
+                    end_col_offset_idx=col_idx + col_span,
+                    column_header=col_header,
+                    row_header=((not col_header) and html_cell.name == "th"),
+                )
+                data.table_cells.append(table_cell)
+
+        return data
+
     def _add_table(
         self, doc: DoclingDocument, parent: NodeItem, table_xml_component: Table
     ) -> None:
@@ -543,8 +649,7 @@ class JatsDocumentBackend(DeclarativeDocumentBackend):
         if not isinstance(table_tag, Tag):
             return
 
-        data = HTMLDocumentBackend.parse_table_data(table_tag)
-
+        data = JatsDocumentBackend.parse_table_data(table_tag)
         # TODO: format label vs caption once styling is supported
         label = table_xml_component["label"]
         caption = table_xml_component["caption"]
@@ -554,7 +659,6 @@ class JatsDocumentBackend(DeclarativeDocumentBackend):
             if table_text
             else None
         )
-
         if data is not None:
             doc.add_table(data=data, parent=parent, caption=table_caption)
 
@@ -609,7 +713,7 @@ class JatsDocumentBackend(DeclarativeDocumentBackend):
         )
         return
 
-    def _walk_linear(  # noqa: C901
+    def _walk_linear(
         self, doc: DoclingDocument, parent: NodeItem, node: etree._Element
     ) -> str:
         skip_tags = ["term"]

docling/backend/xml/uspto_backend.py

@@ -1523,7 +1523,7 @@ class XmlTable:
 
         return ncols_max
 
-    def _parse_table(self, table: Tag) -> TableData:  # noqa: C901
+    def _parse_table(self, table: Tag) -> TableData:
         """Parse the content of a table tag.
 
         Args:

docling/cli/main.py

@@ -66,6 +66,7 @@ from docling.datamodel.vlm_model_specs import (
     GRANITE_VISION_TRANSFORMERS,
     GRANITEDOCLING_MLX,
     GRANITEDOCLING_TRANSFORMERS,
+    GRANITEDOCLING_VLLM,
     SMOLDOCLING_MLX,
     SMOLDOCLING_TRANSFORMERS,
     SMOLDOCLING_VLLM,
@@ -686,6 +687,7 @@ def convert(  # noqa: C901
                             "To run SmolDocling faster, please install mlx-vlm:\n"
                             "pip install mlx-vlm"
                         )
+
             elif vlm_model == VlmModelType.GRANITEDOCLING:
                 pipeline_options.vlm_options = GRANITEDOCLING_TRANSFORMERS
                 if sys.platform == "darwin":
@@ -701,6 +703,9 @@ def convert(  # noqa: C901
             elif vlm_model == VlmModelType.SMOLDOCLING_VLLM:
                 pipeline_options.vlm_options = SMOLDOCLING_VLLM
 
+            elif vlm_model == VlmModelType.GRANITEDOCLING_VLLM:
+                pipeline_options.vlm_options = GRANITEDOCLING_VLLM
+
             pdf_format_option = PdfFormatOption(
                 pipeline_cls=VlmPipeline, pipeline_options=pipeline_options
             )

docling/datamodel/pipeline_options_vlm_model.py

@@ -1,11 +1,13 @@
 from enum import Enum
-from typing import Any, Dict, List, Literal, Optional
+from typing import Any, Dict, List, Literal, Optional, Union
 
 from docling_core.types.doc.page import SegmentedPage
-from pydantic import AnyUrl, BaseModel
+from pydantic import AnyUrl, BaseModel, ConfigDict
+from transformers import StoppingCriteria
 from typing_extensions import deprecated
 
 from docling.datamodel.accelerator_options import AcceleratorDevice
+from docling.models.utils.generation_utils import GenerationStopper
 
 
 class BaseVlmOptions(BaseModel):
@@ -50,9 +52,12 @@ class TransformersPromptStyle(str, Enum):
 
 
 class InlineVlmOptions(BaseVlmOptions):
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
     kind: Literal["inline_model_options"] = "inline_model_options"
 
     repo_id: str
+    revision: str = "main"
     trust_remote_code: bool = False
     load_in_8bit: bool = True
     llm_int8_threshold: float = 6.0
@@ -71,6 +76,7 @@ class InlineVlmOptions(BaseVlmOptions):
     ]
 
     stop_strings: List[str] = []
+    custom_stopping_criteria: List[Union[StoppingCriteria, GenerationStopper]] = []
     extra_generation_config: Dict[str, Any] = {}
     extra_processor_kwargs: Dict[str, Any] = {}
 
@@ -88,6 +94,8 @@ class HuggingFaceVlmOptions(InlineVlmOptions):
 
 
 class ApiVlmOptions(BaseVlmOptions):
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
     kind: Literal["api_model_options"] = "api_model_options"
 
     url: AnyUrl = AnyUrl(
@@ -98,3 +106,6 @@ class ApiVlmOptions(BaseVlmOptions):
     timeout: float = 60
     concurrency: int = 1
     response_format: ResponseFormat
+
+    stop_strings: List[str] = []
+    custom_stopping_criteria: List[Union[GenerationStopper]] = []

docling/datamodel/vlm_model_specs.py

@@ -29,12 +29,20 @@ GRANITEDOCLING_TRANSFORMERS = InlineVlmOptions(
         AcceleratorDevice.CPU,
         AcceleratorDevice.CUDA,
     ],
+    extra_generation_config=dict(skip_special_tokens=False),
     scale=2.0,
     temperature=0.0,
     max_new_tokens=8192,
     stop_strings=["</doctag>", "<|end_of_text|>"],
 )
 
+GRANITEDOCLING_VLLM = GRANITEDOCLING_TRANSFORMERS.model_copy()
+GRANITEDOCLING_VLLM.inference_framework = InferenceFramework.VLLM
+GRANITEDOCLING_VLLM.revision = (
+    "untied"  # change back to "main" with next vllm relase after 0.10.2
+)
+
+
 GRANITEDOCLING_MLX = InlineVlmOptions(
     repo_id="ibm-granite/granite-docling-258M-mlx",
     prompt="Convert this page to docling.",
@@ -302,3 +310,4 @@ class VlmModelType(str, Enum):
     GRANITE_VISION_OLLAMA = "granite_vision_ollama"
     GOT_OCR_2 = "got_ocr_2"
     GRANITEDOCLING = "granite_docling"
+    GRANITEDOCLING_VLLM = "granite_docling_vllm"

docling/models/api_vlm_model.py

@@ -1,12 +1,18 @@
 from collections.abc import Iterable
 from concurrent.futures import ThreadPoolExecutor
 
+from transformers import StoppingCriteria
+
 from docling.datamodel.base_models import Page, VlmPrediction
 from docling.datamodel.document import ConversionResult
 from docling.datamodel.pipeline_options_vlm_model import ApiVlmOptions
 from docling.exceptions import OperationNotAllowed
 from docling.models.base_model import BasePageModel
-from docling.utils.api_image_request import api_image_request
+from docling.models.utils.generation_utils import GenerationStopper
+from docling.utils.api_image_request import (
+    api_image_request,
+    api_image_request_streaming,
+)
 from docling.utils.profiling import TimeRecorder
 
 
@@ -41,19 +47,43 @@ class ApiVlmModel(BasePageModel):
             assert page._backend is not None
             if not page._backend.is_valid():
                 return page
-            else:
-                with TimeRecorder(conv_res, "vlm"):
-                    assert page.size is not None
 
-                    hi_res_image = page.get_image(
-                        scale=self.vlm_options.scale, max_size=self.vlm_options.max_size
-                    )
-                    assert hi_res_image is not None
-                    if hi_res_image:
-                        if hi_res_image.mode != "RGB":
-                            hi_res_image = hi_res_image.convert("RGB")
+            with TimeRecorder(conv_res, "vlm"):
+                assert page.size is not None
+
+                hi_res_image = page.get_image(
+                    scale=self.vlm_options.scale, max_size=self.vlm_options.max_size
+                )
+                assert hi_res_image is not None
+                if hi_res_image and hi_res_image.mode != "RGB":
+                    hi_res_image = hi_res_image.convert("RGB")
 
-                    prompt = self.vlm_options.build_prompt(page.parsed_page)
+                prompt = self.vlm_options.build_prompt(page.parsed_page)
+
+                if self.vlm_options.custom_stopping_criteria:
+                    # Instantiate any GenerationStopper classes before passing to streaming
+                    instantiated_stoppers = []
+                    for criteria in self.vlm_options.custom_stopping_criteria:
+                        if isinstance(criteria, GenerationStopper):
+                            instantiated_stoppers.append(criteria)
+                        elif isinstance(criteria, type) and issubclass(
+                            criteria, GenerationStopper
+                        ):
+                            instantiated_stoppers.append(criteria())
+                        # Skip non-GenerationStopper criteria (should have been caught in validation)
+
+                    # Streaming path with early abort support
+                    page_tags = api_image_request_streaming(
+                        image=hi_res_image,
+                        prompt=prompt,
+                        url=self.vlm_options.url,
+                        timeout=self.timeout,
+                        headers=self.vlm_options.headers,
+                        generation_stoppers=instantiated_stoppers,
+                        **self.params,
+                    )
+                else:
+                    # Non-streaming fallback (existing behavior)
                     page_tags = api_image_request(
                         image=hi_res_image,
                         prompt=prompt,
@@ -63,10 +93,9 @@ class ApiVlmModel(BasePageModel):
                         **self.params,
                     )
 
-                    page_tags = self.vlm_options.decode_response(page_tags)
-                    page.predictions.vlm_response = VlmPrediction(text=page_tags)
-
-                return page
+                page_tags = self.vlm_options.decode_response(page_tags)
+                page.predictions.vlm_response = VlmPrediction(text=page_tags)
+            return page
 
         with ThreadPoolExecutor(max_workers=self.concurrency) as executor:
             yield from executor.map(_vlm_request, page_batch)

docling/models/base_model.py

@@ -88,7 +88,8 @@ class BaseVlmPageModel(BasePageModel, BaseVlmModel):
 
         if self.vlm_options.transformers_prompt_style == TransformersPromptStyle.RAW:
             return user_prompt
-
+        elif self.vlm_options.transformers_prompt_style == TransformersPromptStyle.NONE:
+            return ""
         elif self.vlm_options.repo_id == "microsoft/Phi-4-multimodal-instruct":
             _log.debug("Using specialized prompt for Phi-4")
             # Note: This might need adjustment for VLLM vs transformers

docling/models/readingorder_model.py

@@ -103,7 +103,7 @@ class ReadingOrderModel:
             else:
                 doc.add_text(parent=doc_item, label=c_label, text=c_text, prov=c_prov)
 
-    def _readingorder_elements_to_docling_doc(  # noqa: C901
+    def _readingorder_elements_to_docling_doc(
         self,
         conv_res: ConversionResult,
         ro_elements: List[ReadingOrderPageElement],

docling/models/utils/generation_utils.py

@@ -0,0 +1,157 @@
+import logging
+import re
+import sys
+from abc import abstractmethod
+from typing import List
+
+from transformers import StoppingCriteria
+
+_log = logging.getLogger(__name__)
+
+
+class GenerationStopper:
+    """
+    Base interface for stopping logic.
+    - should_stop(s): True to stop given the current decoded text window.
+    - lookback_tokens(): how many tokens should be considered (default: sys.maxsize).
+    """
+
+    @abstractmethod
+    def should_stop(self, s: str) -> bool:
+        pass
+
+    def lookback_tokens(self) -> int:
+        return sys.maxsize
+
+
+class DocTagsRepetitionStopper(GenerationStopper):
+    """
+    Detects repetitive <tag>...<loc_x><loc_y><loc_w><loc_h>text</tag> blocks,
+    but only when repeats are **consecutive** and both tag & inner text are identical.
+
+    Performance:
+    - Heavy check runs every N calls (default 32).
+    - Only decodes the last LOOKBACK_TOKENS tokens per sequence (default 200).
+    """
+
+    def __init__(self, *, N: int = 32, lookback_tokens: int = 200):
+        self.N = max(1, int(N))
+        self._lookback_tokens = max(1, int(lookback_tokens))
+        self._call_count = 0
+
+        # <tag> ... <loc_x><loc_y><loc_w><loc_h> text ... </tag>
+        self._PATTERN = re.compile(
+            r"""
+            <(?P<tag>[a-zA-Z0-9_]+)>\s*
+            (?P<prefix>.*?)?
+            <loc_(?P<x>\d+)><loc_(?P<y>\d+)><loc_(?P<w>\d+)><loc_(?P<h>\d+)>
+            (?P<text>.*?)
+            </(?P=tag)>
+            """,
+            re.DOTALL | re.VERBOSE,
+        )
+
+    # --- small helper ---
+    def _regular(self, vals: List[int]) -> bool:
+        """3+ strictly increasing values with ~regular spacing (±20%)."""
+        if len(vals) < 3:
+            return False
+        diffs = [b - a for a, b in zip(vals, vals[1:])]
+        if any(d <= 0 for d in diffs):
+            return False
+        mean = sum(diffs) / len(diffs)
+        tol = 0.2 * mean
+        return all(abs(d - mean) <= tol for d in diffs)
+
+    def should_stop(self, s: str) -> bool:
+        """
+        Trip only on **consecutive** runs (no other matched blocks between) of ≥3 items
+        with the same <tag> and identical inner text, where within that run we see:
+          - any exact duplicate (x,y,w,h), or
+          - stable X/W with regular Y progression, or
+          - stable Y/H with regular X progression.
+        """
+        # Stream matches and evaluate runs on-the-fly to stay compact and fast.
+        prev_tag = prev_text = None
+        run = []  # list of (x,y,w,h)
+
+        def run_repetitive(boxes: List[tuple]) -> bool:
+            if len(boxes) < 3:
+                return False
+            # duplicates?
+            if len(set(boxes)) < len(boxes):
+                return True
+            xs, ys, ws, hs = zip(*boxes)
+            x_stable = all(x == xs[0] for x in xs)
+            y_stable = all(y == ys[0] for y in ys)
+            w_stable = all(w == ws[0] for w in ws)
+            h_stable = all(h == hs[0] for h in hs)
+            # horizontal (down the page): X/W stable, Y regular
+            if (x_stable or w_stable) and self._regular(list(ys)):
+                return True
+            # vertical (across): Y/H stable, X regular
+            if (y_stable or h_stable) and self._regular(list(xs)):
+                return True
+            return False
+
+        for m in self._PATTERN.finditer(s):
+            tag, text = m.group("tag"), m.group("text")
+            box = (
+                int(m.group("x")),
+                int(m.group("y")),
+                int(m.group("w")),
+                int(m.group("h")),
+            )
+
+            if prev_tag == tag and prev_text == text:
+                run.append(box)  # consecutive same-tag+text
+            else:
+                # evaluate previous run before starting a new one
+                if run_repetitive(run):
+                    return True
+                prev_tag, prev_text = tag, text
+                run = [box]
+
+        # check the last run
+        return run_repetitive(run)
+
+
+class HFStoppingCriteriaWrapper(StoppingCriteria):
+    """
+    Adapts any GenerationStopper to HuggingFace Transformers.
+    Decodes exactly min(seq_len, stopper.lookback_tokens()) tokens from the end.
+    """
+
+    def __init__(
+        self,
+        tokenizer,
+        stopper: GenerationStopper,
+        *,
+        skip_special_tokens: bool = False,
+    ):
+        self.tokenizer = tokenizer
+        self.stopper = stopper
+        self.skip_special_tokens = skip_special_tokens
+
+    def __call__(self, input_ids, scores, **kwargs) -> bool:
+        lb = max(1, int(self.stopper.lookback_tokens()))
+        for seq in input_ids:  # (batch, seq_len)
+            window = seq[-lb:]  # slicing handles lb > len(seq)
+            try:
+                text = self.tokenizer.decode(
+                    window, skip_special_tokens=self.skip_special_tokens
+                )
+            except Exception as e:
+                _log.info(f"Decoding failed for stopping check: {e}")
+                continue
+
+            try:
+                if self.stopper.should_stop(text):
+                    _log.info(
+                        "HF wrapper: stopping due to TextStopper.should_stop==True"
+                    )
+                    return True
+            except Exception as e:
+                _log.info(f"Error in TextStopper.should_stop: {e}")
+                continue
+        return False

docling/models/utils/hf_model_download.py

@@ -34,7 +34,12 @@ class HuggingFaceModelDownloadMixin:
         local_dir: Optional[Path] = None,
         force: bool = False,
         progress: bool = False,
+        revision: Optional[str] = None,
     ) -> Path:
         return download_hf_model(
-            repo_id=repo_id, local_dir=local_dir, force=force, progress=progress
+            repo_id=repo_id,
+            local_dir=local_dir,
+            force=force,
+            progress=progress,
+            revision=revision,
         )