docling-core 2.24.1__py3-none-any.whl → 2.26.0__py3-none-any.whl

docling_core/transforms/chunker/hierarchical_chunker.py

@@ -11,24 +11,36 @@ import logging
 import re
 from typing import Any, ClassVar, Final, Iterator, Literal, Optional
 
-from pandas import DataFrame
-from pydantic import Field, StringConstraints, field_validator
-from typing_extensions import Annotated
-
+from pydantic import ConfigDict, Field, StringConstraints, field_validator
+from typing_extensions import Annotated, override
+
+from docling_core.experimental.serializer.base import (
+    BaseDocSerializer,
+    BaseSerializerProvider,
+    BaseTableSerializer,
+    SerializationResult,
+)
+from docling_core.experimental.serializer.common import create_ser_result
+from docling_core.experimental.serializer.markdown import (
+    MarkdownDocSerializer,
+    MarkdownParams,
+)
 from docling_core.search.package import VERSION_PATTERN
 from docling_core.transforms.chunker import BaseChunk, BaseChunker, BaseMeta
 from docling_core.types import DoclingDocument as DLDocument
+from docling_core.types.doc.base import ImageRefMode
 from docling_core.types.doc.document import (
-    CodeItem,
     DocItem,
+    DoclingDocument,
     DocumentOrigin,
+    InlineGroup,
     LevelNumber,
-    ListItem,
+    OrderedList,
     SectionHeaderItem,
     TableItem,
-    TextItem,
+    TitleItem,
+    UnorderedList,
 )
-from docling_core.types.doc.labels import DocItemLabel
 
 _VERSION: Final = "1.0.0"
 
@@ -64,7 +76,8 @@ class DocMeta(BaseMeta):
         alias=_KEY_HEADINGS,
         min_length=1,
     )
-    captions: Optional[list[str]] = Field(
+    captions: Optional[list[str]] = Field(  # deprecated
+        deprecated=True,
         default=None,
         alias=_KEY_CAPTIONS,
         min_length=1,
@@ -110,6 +123,76 @@ class DocChunk(BaseChunk):
     meta: DocMeta
 
 
+class TripletTableSerializer(BaseTableSerializer):
+    """Triplet-based table item serializer."""
+
+    @override
+    def serialize(
+        self,
+        *,
+        item: TableItem,
+        doc_serializer: BaseDocSerializer,
+        doc: DoclingDocument,
+        **kwargs,
+    ) -> SerializationResult:
+        """Serializes the passed item."""
+        parts: list[SerializationResult] = []
+
+        cap_res = doc_serializer.serialize_captions(
+            item=item,
+            **kwargs,
+        )
+        if cap_res.text:
+            parts.append(cap_res)
+
+        if item.self_ref not in doc_serializer.get_excluded_refs(**kwargs):
+            table_df = item.export_to_dataframe()
+            if table_df.shape[0] >= 1 and table_df.shape[1] >= 2:
+
+                # copy header as first row and shift all rows by one
+                table_df.loc[-1] = table_df.columns  # type: ignore[call-overload]
+                table_df.index = table_df.index + 1
+                table_df = table_df.sort_index()
+
+                rows = [str(item).strip() for item in table_df.iloc[:, 0].to_list()]
+                cols = [str(item).strip() for item in table_df.iloc[0, :].to_list()]
+
+                nrows = table_df.shape[0]
+                ncols = table_df.shape[1]
+                table_text_parts = [
+                    f"{rows[i]}, {cols[j]} = {str(table_df.iloc[i, j]).strip()}"
+                    for i in range(1, nrows)
+                    for j in range(1, ncols)
+                ]
+                table_text = ". ".join(table_text_parts)
+                parts.append(create_ser_result(text=table_text, span_source=item))
+
+        text_res = "\n\n".join([r.text for r in parts])
+
+        return create_ser_result(text=text_res, span_source=parts)
+
+
+class ChunkingDocSerializer(MarkdownDocSerializer):
+    """Doc serializer used for chunking purposes."""
+
+    table_serializer: BaseTableSerializer = TripletTableSerializer()
+    params: MarkdownParams = MarkdownParams(
+        image_mode=ImageRefMode.PLACEHOLDER,
+        image_placeholder="",
+        escape_underscores=False,
+        escape_html=False,
+    )
+
+
+class ChunkingSerializerProvider(BaseSerializerProvider):
+    """Serializer provider used for chunking purposes."""
+
+    @override
+    def get_serializer(self, doc: DoclingDocument) -> BaseDocSerializer:
+        """Get the associated serializer."""
+        return ChunkingDocSerializer(doc=doc)
+
+
 class HierarchicalChunker(BaseChunker):
     r"""Chunker implementation leveraging the document layout.
 
@@ -119,31 +202,18 @@ class HierarchicalChunker(BaseChunker):
         delim (str): Delimiter to use for merging text. Defaults to "\n".
     """
 
-    merge_list_items: bool = True
-
-    @classmethod
-    def _triplet_serialize(cls, table_df: DataFrame) -> str:
-
-        # copy header as first row and shift all rows by one
-        table_df.loc[-1] = table_df.columns  # type: ignore[call-overload]
-        table_df.index = table_df.index + 1
-        table_df = table_df.sort_index()
-
-        rows = [str(item).strip() for item in table_df.iloc[:, 0].to_list()]
-        cols = [str(item).strip() for item in table_df.iloc[0, :].to_list()]
+    model_config = ConfigDict(arbitrary_types_allowed=True)
 
-        nrows = table_df.shape[0]
-        ncols = table_df.shape[1]
-        texts = [
-            f"{rows[i]}, {cols[j]} = {str(table_df.iloc[i, j]).strip()}"
-            for i in range(1, nrows)
-            for j in range(1, ncols)
-        ]
-        output_text = ". ".join(texts)
+    serializer_provider: BaseSerializerProvider = ChunkingSerializerProvider()
 
-        return output_text
+    # deprecated:
+    merge_list_items: Annotated[bool, Field(deprecated=True)] = True
 
-    def chunk(self, dl_doc: DLDocument, **kwargs: Any) -> Iterator[BaseChunk]:
+    def chunk(
+        self,
+        dl_doc: DLDocument,
+        **kwargs: Any,
+    ) -> Iterator[BaseChunk]:
         r"""Chunk the provided document.
 
         Args:
@@ -152,90 +222,41 @@ class HierarchicalChunker(BaseChunker):
         Yields:
             Iterator[Chunk]: iterator over extracted chunks
         """
+        my_doc_ser = self.serializer_provider.get_serializer(doc=dl_doc)
         heading_by_level: dict[LevelNumber, str] = {}
-        list_items: list[TextItem] = []
-        for item, level in dl_doc.iterate_items():
-            captions = None
-            if isinstance(item, DocItem):
-
-                # first handle any merging needed
-                if self.merge_list_items:
-                    if isinstance(
-                        item, ListItem
-                    ) or (  # TODO remove when all captured as ListItem:
-                        isinstance(item, TextItem)
-                        and item.label == DocItemLabel.LIST_ITEM
-                    ):
-                        list_items.append(item)
-                        continue
-                    elif list_items:  # need to yield
-                        yield DocChunk(
-                            text=self.delim.join([i.text for i in list_items]),
-                            meta=DocMeta(
-                                doc_items=list_items,
-                                headings=[
-                                    heading_by_level[k]
-                                    for k in sorted(heading_by_level)
-                                ]
-                                or None,
-                                origin=dl_doc.origin,
-                            ),
-                        )
-                        list_items = []  # reset
-
-                if isinstance(item, SectionHeaderItem) or (
-                    isinstance(item, TextItem)
-                    and item.label in [DocItemLabel.SECTION_HEADER, DocItemLabel.TITLE]
-                ):
-                    level = (
-                        item.level
-                        if isinstance(item, SectionHeaderItem)
-                        else (0 if item.label == DocItemLabel.TITLE else 1)
-                    )
-                    heading_by_level[level] = item.text
-
-                    # remove headings of higher level as they just went out of scope
-                    keys_to_del = [k for k in heading_by_level if k > level]
-                    for k in keys_to_del:
-                        heading_by_level.pop(k, None)
-                    continue
-
-                if (
-                    isinstance(item, TextItem)
-                    or ((not self.merge_list_items) and isinstance(item, ListItem))
-                    or isinstance(item, CodeItem)
-                ):
-                    text = item.text
-                elif isinstance(item, TableItem):
-                    table_df = item.export_to_dataframe()
-                    if table_df.shape[0] < 1 or table_df.shape[1] < 2:
-                        # at least two cols needed, as first column contains row headers
-                        continue
-                    text = self._triplet_serialize(table_df=table_df)
-                    captions = [
-                        c.text for c in [r.resolve(dl_doc) for r in item.captions]
-                    ] or None
-                else:
-                    continue
+        visited: set[str] = set()
+        ser_res = create_ser_result()
+        excluded_refs = my_doc_ser.get_excluded_refs(**kwargs)
+        for item, level in dl_doc.iterate_items(with_groups=True):
+            if item.self_ref in excluded_refs:
+                continue
+            if isinstance(item, (TitleItem, SectionHeaderItem)):
+                level = item.level if isinstance(item, SectionHeaderItem) else 0
+                heading_by_level[level] = item.text
+
+                # remove headings of higher level as they just went out of scope
+                keys_to_del = [k for k in heading_by_level if k > level]
+                for k in keys_to_del:
+                    heading_by_level.pop(k, None)
+                continue
+            elif (
+                isinstance(item, (OrderedList, UnorderedList, InlineGroup, DocItem))
+                and item.self_ref not in visited
+            ):
+                ser_res = my_doc_ser.serialize(item=item, visited=visited)
+            else:
+                continue
+
+            if not ser_res.text:
+                continue
+            if doc_items := [u.item for u in ser_res.spans]:
                 c = DocChunk(
-                    text=text,
+                    text=ser_res.text,
                     meta=DocMeta(
-                        doc_items=[item],
+                        doc_items=doc_items,
                         headings=[heading_by_level[k] for k in sorted(heading_by_level)]
                         or None,
-                        captions=captions,
                         origin=dl_doc.origin,
                     ),
                 )
                 yield c
-
-        if self.merge_list_items and list_items:  # need to yield
-            yield DocChunk(
-                text=self.delim.join([i.text for i in list_items]),
-                meta=DocMeta(
-                    doc_items=list_items,
-                    headings=[heading_by_level[k] for k in sorted(heading_by_level)]
-                    or None,
-                    origin=dl_doc.origin,
-                ),
-            )

docling_core/transforms/chunker/hybrid_chunker.py

@@ -4,13 +4,24 @@
 #
 
 """Hybrid chunker implementation leveraging both doc structure & token awareness."""
-
 import warnings
+from functools import cached_property
 from typing import Any, Iterable, Iterator, Optional, Union
 
-from pydantic import BaseModel, ConfigDict, PositiveInt, TypeAdapter, model_validator
+from pydantic import (
+    BaseModel,
+    ConfigDict,
+    PositiveInt,
+    TypeAdapter,
+    computed_field,
+    model_validator,
+)
 from typing_extensions import Self
 
+from docling_core.transforms.chunker.hierarchical_chunker import (
+    ChunkingSerializerProvider,
+)
+
 try:
     import semchunk
     from transformers import AutoTokenizer, PreTrainedTokenizerBase
@@ -20,6 +31,10 @@ except ImportError:
         "`pip install 'docling-core[chunking]'`"
     )
 
+from docling_core.experimental.serializer.base import (
+    BaseDocSerializer,
+    BaseSerializerProvider,
+)
 from docling_core.transforms.chunker import (
     BaseChunk,
     BaseChunker,
@@ -28,7 +43,6 @@ from docling_core.transforms.chunker import (
     HierarchicalChunker,
 )
 from docling_core.types import DoclingDocument
-from docling_core.types.doc.document import TextItem
 
 
 class HybridChunker(BaseChunker):
@@ -50,7 +64,7 @@ class HybridChunker(BaseChunker):
     max_tokens: int = None  # type: ignore[assignment]
     merge_peers: bool = True
 
-    _inner_chunker: HierarchicalChunker = HierarchicalChunker()
+    serializer_provider: BaseSerializerProvider = ChunkingSerializerProvider()
 
     @model_validator(mode="after")
     def _patch_tokenizer_and_max_tokens(self) -> Self:
@@ -65,6 +79,11 @@ class HybridChunker(BaseChunker):
             )
         return self
 
+    @computed_field  # type: ignore[misc]
+    @cached_property
+    def _inner_chunker(self) -> HierarchicalChunker:
+        return HierarchicalChunker(serializer_provider=self.serializer_provider)
+
     def _count_text_tokens(self, text: Optional[Union[str, list[str]]]):
         if text is None:
             return 0
@@ -81,7 +100,7 @@ class HybridChunker(BaseChunker):
         other_len: int
 
     def _count_chunk_tokens(self, doc_chunk: DocChunk):
-        ser_txt = self.serialize(chunk=doc_chunk)
+        ser_txt = self.contextualize(chunk=doc_chunk)
         return len(self._tokenizer.tokenize(text=ser_txt))
 
     def _doc_chunk_length(self, doc_chunk: DocChunk):
@@ -94,7 +113,11 @@ class HybridChunker(BaseChunker):
         )
 
     def _make_chunk_from_doc_items(
-        self, doc_chunk: DocChunk, window_start: int, window_end: int
+        self,
+        doc_chunk: DocChunk,
+        window_start: int,
+        window_end: int,
+        doc_serializer: BaseDocSerializer,
     ):
         doc_items = doc_chunk.meta.doc_items[window_start : window_end + 1]
         meta = DocMeta(
@@ -106,18 +129,21 @@ class HybridChunker(BaseChunker):
         window_text = (
             doc_chunk.text
             if len(doc_chunk.meta.doc_items) == 1
+            # TODO: merging should ideally be done by the serializer:
             else self.delim.join(
                 [
-                    doc_item.text
+                    res_text
                     for doc_item in doc_items
-                    if isinstance(doc_item, TextItem)
+                    if (res_text := doc_serializer.serialize(item=doc_item).text)
                 ]
             )
         )
         new_chunk = DocChunk(text=window_text, meta=meta)
         return new_chunk
 
-    def _split_by_doc_items(self, doc_chunk: DocChunk) -> list[DocChunk]:
+    def _split_by_doc_items(
+        self, doc_chunk: DocChunk, doc_serializer: BaseDocSerializer
+    ) -> list[DocChunk]:
         chunks = []
         window_start = 0
         window_end = 0  # an inclusive index
@@ -127,6 +153,7 @@ class HybridChunker(BaseChunker):
                 doc_chunk=doc_chunk,
                 window_start=window_start,
                 window_end=window_end,
+                doc_serializer=doc_serializer,
             )
             if self._count_chunk_tokens(doc_chunk=new_chunk) <= self.max_tokens:
                 if window_end < num_items - 1:
@@ -153,6 +180,7 @@ class HybridChunker(BaseChunker):
                     doc_chunk=doc_chunk,
                     window_start=window_start,
                     window_end=window_end - 1,
+                    doc_serializer=doc_serializer,
                 )
                 window_start = window_end
             chunks.append(new_chunk)
@@ -199,6 +227,7 @@ class HybridChunker(BaseChunker):
                 chks = chunks[window_start : window_end + 1]
                 doc_items = [it for chk in chks for it in chk.meta.doc_items]
                 candidate = DocChunk(
+                    # TODO: merging should ideally be done by the serializer:
                     text=self.delim.join([chk.text for chk in chks]),
                     meta=DocMeta(
                         doc_items=doc_items,
@@ -231,7 +260,11 @@ class HybridChunker(BaseChunker):
 
         return output_chunks
 
-    def chunk(self, dl_doc: DoclingDocument, **kwargs: Any) -> Iterator[BaseChunk]:
+    def chunk(
+        self,
+        dl_doc: DoclingDocument,
+        **kwargs: Any,
+    ) -> Iterator[BaseChunk]:
         r"""Chunk the provided document.
 
         Args:
@@ -240,9 +273,18 @@ class HybridChunker(BaseChunker):
         Yields:
             Iterator[Chunk]: iterator over extracted chunks
         """
+        my_doc_ser = self.serializer_provider.get_serializer(doc=dl_doc)
         res: Iterable[DocChunk]
-        res = self._inner_chunker.chunk(dl_doc=dl_doc, **kwargs)  # type: ignore
-        res = [x for c in res for x in self._split_by_doc_items(c)]
+        res = self._inner_chunker.chunk(
+            dl_doc=dl_doc,
+            doc_serializer=my_doc_ser,
+            **kwargs,
+        )  # type: ignore
+        res = [
+            x
+            for c in res
+            for x in self._split_by_doc_items(c, doc_serializer=my_doc_ser)
+        ]
         res = [x for c in res for x in self._split_using_plain_text(c)]
         if self.merge_peers:
             res = self._merge_chunks_with_matching_metadata(res)

docling_core/types/doc/base.py

@@ -182,7 +182,10 @@ class BoundingBox(BaseModel):
     ) -> float:
         """intersection_over_self."""
         intersection_area = self.intersection_area_with(other=other)
-        return intersection_area / self.area()
+        if self.area() > 0:
+            return intersection_area / self.area()
+        else:
+            return 0.0
 
     def to_bottom_left_origin(self, page_height: float) -> "BoundingBox":
         """to_bottom_left_origin.