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

docling_core/experimental/serializer/base.py

@@ -11,6 +11,7 @@ from typing import Optional, Union
 from pydantic import AnyUrl, BaseModel
 
 from docling_core.types.doc.document import (
+    DocItem,
     DoclingDocument,
     FloatingItem,
     FormItem,
@@ -25,10 +26,19 @@ from docling_core.types.doc.document import (
 )
 
 
+class Span(BaseModel):
+    """Class encapsulating fine-granular document span information."""
+
+    item: DocItem
+    # prov_idx: Optional[PositiveInt] = None  # None to be interpreted as whole DocItem
+
+
 class SerializationResult(BaseModel):
     """SerializationResult."""
 
-    text: str
+    text: str = ""
+    spans: list[Span] = []
+    # group: Optional[GroupItem] = None  # set when result reflects specific group item
 
 
 class BaseTextSerializer(ABC):
@@ -163,7 +173,9 @@ class BaseDocSerializer(ABC):
     """Base class for document serializers."""
 
     @abstractmethod
-    def serialize(self, **kwargs) -> SerializationResult:
+    def serialize(
+        self, *, item: Optional[NodeItem] = None, **kwargs
+    ) -> SerializationResult:
         """Run the serialization."""
         ...
 
@@ -225,3 +237,12 @@ class BaseDocSerializer(ABC):
     def get_excluded_refs(self, **kwargs) -> list[str]:
         """Get references to excluded items."""
         ...
+
+
+class BaseSerializerProvider(ABC):
+    """Base class for document serializer providers."""
+
+    @abstractmethod
+    def get_serializer(self, doc: DoclingDocument) -> BaseDocSerializer:
+        """Get a the associated serializer."""
+        ...

docling_core/experimental/serializer/common.py

@@ -25,6 +25,7 @@ from docling_core.experimental.serializer.base import (
     BaseTableSerializer,
     BaseTextSerializer,
     SerializationResult,
+    Span,
 )
 from docling_core.types.doc.document import (
     DOCUMENT_TOKENS_EXPORT_LABELS,
@@ -49,6 +50,38 @@ _DEFAULT_LABELS = DOCUMENT_TOKENS_EXPORT_LABELS
 _DEFAULT_LAYERS = {cl for cl in ContentLayer}
 
 
+def create_ser_result(
+    *,
+    text: str = "",
+    span_source: Union[DocItem, list[SerializationResult]] = [],
+) -> SerializationResult:
+    """Function for creating `SerializationResult` instances.
+
+    Args:
+        text: the text the use. Defaults to "".
+        span_source: the item or list of results to use as span source. Defaults to [].
+
+    Returns:
+        The created `SerializationResult`.
+    """
+    spans: list[Span]
+    if isinstance(span_source, DocItem):
+        spans = [Span(item=span_source)]
+    else:
+        results: list[SerializationResult] = span_source
+        spans = []
+        span_ids: set[str] = set()
+        for ser_res in results:
+            for span in ser_res.spans:
+                if (span_id := span.item.self_ref) not in span_ids:
+                    span_ids.add(span_id)
+                    spans.append(span)
+    return SerializationResult(
+        text=text,
+        spans=spans,
+    )
+
+
 class CommonParams(BaseModel):
     """Common serialization parameters."""
 
@@ -150,20 +183,26 @@ class DocSerializer(BaseModel, BaseDocSerializer):
         return refs
 
     @abstractmethod
-    def serialize_page(self, parts: list[SerializationResult]) -> SerializationResult:
+    def serialize_page(
+        self, *, parts: list[SerializationResult], **kwargs
+    ) -> SerializationResult:
         """Serialize a page out of its parts."""
         ...
 
     @abstractmethod
-    def serialize_doc(self, pages: list[SerializationResult]) -> SerializationResult:
+    def serialize_doc(
+        self, *, pages: dict[Optional[int], SerializationResult], **kwargs
+    ) -> SerializationResult:
         """Serialize a document out of its pages."""
         ...
 
     def _serialize_body(self) -> SerializationResult:
         """Serialize the document body."""
         # find page ranges if available; otherwise regard whole doc as a single page
-        last_page: Optional[int] = None
-        starts: list[int] = []
+        prev_start: int = 0
+        prev_page_nr: Optional[int] = None
+        range_by_page_nr: dict[Optional[int], tuple[int, int]] = {}
+
         for ix, (item, _) in enumerate(
             self.doc.iterate_items(
                 with_groups=True,
@@ -173,28 +212,30 @@ class DocSerializer(BaseModel, BaseDocSerializer):
         ):
             if isinstance(item, DocItem):
                 if item.prov:
-                    if last_page is None or item.prov[0].page_no > last_page:
-                        starts.append(ix)
-                        last_page = item.prov[0].page_no
-        page_ranges = [
-            (
-                (starts[i] if i > 0 else 0),
-                (starts[i + 1] if i < len(starts) - 1 else sys.maxsize),
-            )
-            for i, _ in enumerate(starts)
-        ] or [
-            (0, sys.maxsize)
-        ]  # use whole range if no pages detected
+                    page_no = item.prov[0].page_no
+                    if prev_page_nr is None or page_no > prev_page_nr:
+                        if prev_page_nr is not None:  # close previous range
+                            range_by_page_nr[prev_page_nr] = (prev_start, ix)
+
+                        prev_start = ix
+                        # could alternatively always start 1st page from 0:
+                        # prev_start = ix if prev_page_nr is not None else 0
+
+                        prev_page_nr = page_no
+
+        # close last (and single if no pages) range
+        range_by_page_nr[prev_page_nr] = (prev_start, sys.maxsize)
 
-        page_results: list[SerializationResult] = []
-        for page_range in page_ranges:
+        page_results: dict[Optional[int], SerializationResult] = {}
+        for page_nr in range_by_page_nr:
+            page_range = range_by_page_nr[page_nr]
             params_to_pass = deepcopy(self.params)
             params_to_pass.start_idx = page_range[0]
             params_to_pass.stop_idx = page_range[1]
             subparts = self.get_parts(**params_to_pass.model_dump())
-            page_res = self.serialize_page(subparts)
-            page_results.append(page_res)
-        res = self.serialize_doc(page_results)
+            page_res = self.serialize_page(parts=subparts)
+            page_results[page_nr] = page_res
+        res = self.serialize_doc(pages=page_results)
         return res
 
     @override
@@ -209,7 +250,8 @@ class DocSerializer(BaseModel, BaseDocSerializer):
     ) -> SerializationResult:
         """Serialize a given node."""
         my_visited: set[str] = visited if visited is not None else set()
-        empty_res = SerializationResult(text="")
+        my_kwargs = self.params.merge_with_patch(patch=kwargs).model_dump()
+        empty_res = create_ser_result()
         if item is None or item == self.doc.body:
             if self.doc.body.self_ref not in my_visited:
                 my_visited.add(self.doc.body.self_ref)
@@ -217,6 +259,8 @@ class DocSerializer(BaseModel, BaseDocSerializer):
             else:
                 return empty_res
 
+        my_visited.add(item.self_ref)
+
         ########
         # groups
         ########
@@ -228,7 +272,7 @@ class DocSerializer(BaseModel, BaseDocSerializer):
                 list_level=list_level,
                 is_inline_scope=is_inline_scope,
                 visited=my_visited,
-                **kwargs,
+                **my_kwargs,
             )
         elif isinstance(item, InlineGroup):
             part = self.inline_serializer.serialize(
@@ -237,7 +281,7 @@ class DocSerializer(BaseModel, BaseDocSerializer):
                 doc=self.doc,
                 list_level=list_level,
                 visited=my_visited,
-                **kwargs,
+                **my_kwargs,
             )
         ###########
         # doc items
@@ -253,7 +297,7 @@ class DocSerializer(BaseModel, BaseDocSerializer):
                         doc_serializer=self,
                         doc=self.doc,
                         is_inline_scope=is_inline_scope,
-                        **kwargs,
+                        **my_kwargs,
                     )
                     if item.self_ref not in self.get_excluded_refs(**kwargs)
                     else empty_res
@@ -263,7 +307,7 @@ class DocSerializer(BaseModel, BaseDocSerializer):
                 item=item,
                 doc_serializer=self,
                 doc=self.doc,
-                **kwargs,
+                **my_kwargs,
             )
         elif isinstance(item, PictureItem):
             part = self.picture_serializer.serialize(
@@ -271,28 +315,28 @@ class DocSerializer(BaseModel, BaseDocSerializer):
                 doc_serializer=self,
                 doc=self.doc,
                 visited=my_visited,
-                **kwargs,
+                **my_kwargs,
             )
         elif isinstance(item, KeyValueItem):
             part = self.key_value_serializer.serialize(
                 item=item,
                 doc_serializer=self,
                 doc=self.doc,
-                **kwargs,
+                **my_kwargs,
             )
         elif isinstance(item, FormItem):
             part = self.form_serializer.serialize(
                 item=item,
                 doc_serializer=self,
                 doc=self.doc,
-                **kwargs,
+                **my_kwargs,
             )
         else:
             part = self.fallback_serializer.serialize(
                 item=item,
                 doc_serializer=self,
                 doc=self.doc,
-                **kwargs,
+                **my_kwargs,
             )
         return part
 
@@ -393,15 +437,16 @@ class DocSerializer(BaseModel, BaseDocSerializer):
     ) -> SerializationResult:
         """Serialize the item's captions."""
         params = self.params.merge_with_patch(patch=kwargs)
+        results: list[SerializationResult] = []
         if DocItemLabel.CAPTION in params.labels:
-            text_parts: list[str] = [
-                it.text
+            results = [
+                create_ser_result(text=it.text, span_source=it)
                 for cap in item.captions
                 if isinstance(it := cap.resolve(self.doc), TextItem)
                 and it.self_ref not in self.get_excluded_refs(**kwargs)
             ]
-            text_res = params.caption_delim.join(text_parts)
+            text_res = params.caption_delim.join([r.text for r in results])
             text_res = self.post_process(text=text_res)
         else:
             text_res = ""
-        return SerializationResult(text=text_res)
+        return create_ser_result(text=text_res, span_source=results)

docling_core/experimental/serializer/doctags.py

@@ -18,7 +18,11 @@ from docling_core.experimental.serializer.base import (
     BaseTextSerializer,
     SerializationResult,
 )
-from docling_core.experimental.serializer.common import CommonParams, DocSerializer
+from docling_core.experimental.serializer.common import (
+    CommonParams,
+    DocSerializer,
+    create_ser_result,
+)
 from docling_core.types.doc.document import (
     CodeItem,
     DocItem,
@@ -33,10 +37,12 @@ from docling_core.types.doc.document import (
     PictureClassificationData,
     PictureItem,
     PictureMoleculeData,
+    PictureTabularChartData,
     TableItem,
     TextItem,
     UnorderedList,
 )
+from docling_core.types.doc.labels import DocItemLabel, PictureClassificationLabel
 from docling_core.types.doc.tokens import DocumentToken
 
 
@@ -135,7 +141,7 @@ class DocTagsTextSerializer(BaseModel, BaseTextSerializer):
         text_res = "".join(parts)
         if wrap_tag is not None:
             text_res = _wrap(text=text_res, wrap_tag=wrap_tag)
-        return SerializationResult(text=text_res)
+        return create_ser_result(text=text_res, span_source=item)
 
 
 class DocTagsTableSerializer(BaseTableSerializer):
@@ -153,7 +159,7 @@ class DocTagsTableSerializer(BaseTableSerializer):
         """Serializes the passed item."""
         params = DocTagsParams(**kwargs)
 
-        parts: list[str] = []
+        res_parts: list[SerializationResult] = []
 
         if item.self_ref not in doc_serializer.get_excluded_refs(**kwargs):
             if params.add_location:
@@ -162,7 +168,7 @@ class DocTagsTableSerializer(BaseTableSerializer):
                     xsize=params.xsize,
                     ysize=params.ysize,
                 )
-                parts.append(loc_text)
+                res_parts.append(create_ser_result(text=loc_text, span_source=item))
 
             otsl_text = item.export_to_otsl(
                 doc=doc,
@@ -171,18 +177,18 @@ class DocTagsTableSerializer(BaseTableSerializer):
                 xsize=params.xsize,
                 ysize=params.ysize,
             )
-            parts.append(otsl_text)
+            res_parts.append(create_ser_result(text=otsl_text, span_source=item))
 
         if params.add_caption:
-            cap_text = doc_serializer.serialize_captions(item=item, **kwargs).text
-            if cap_text:
-                parts.append(cap_text)
+            cap_res = doc_serializer.serialize_captions(item=item, **kwargs)
+            if cap_res.text:
+                res_parts.append(cap_res)
 
-        text_res = "".join(parts)
+        text_res = "".join([r.text for r in res_parts])
         if text_res:
             text_res = _wrap(text=text_res, wrap_tag=DocumentToken.OTSL.value)
 
-        return SerializationResult(text=text_res)
+        return create_ser_result(text=text_res, span_source=res_parts)
 
 
 class DocTagsPictureSerializer(BasePictureSerializer):
@@ -199,7 +205,8 @@ class DocTagsPictureSerializer(BasePictureSerializer):
     ) -> SerializationResult:
         """Serializes the passed item."""
         params = DocTagsParams(**kwargs)
-        parts: list[str] = []
+        res_parts: list[SerializationResult] = []
+        is_chart = False
 
         if item.self_ref not in doc_serializer.get_excluded_refs(**kwargs):
             body = ""
@@ -217,6 +224,16 @@ class DocTagsPictureSerializer(BasePictureSerializer):
             ]
             if len(classifications) > 0:
                 predicted_class = classifications[0].predicted_classes[0].class_name
+                if predicted_class in [
+                    PictureClassificationLabel.PIE_CHART,
+                    PictureClassificationLabel.BAR_CHART,
+                    PictureClassificationLabel.STACKED_BAR_CHART,
+                    PictureClassificationLabel.LINE_CHART,
+                    PictureClassificationLabel.FLOW_CHART,
+                    PictureClassificationLabel.SCATTER_CHART,
+                    PictureClassificationLabel.HEATMAP,
+                ]:
+                    is_chart = True
                 body += DocumentToken.get_picture_classification_token(predicted_class)
 
             smiles_annotations = [
@@ -226,20 +243,35 @@ class DocTagsPictureSerializer(BasePictureSerializer):
                 body += _wrap(
                     text=smiles_annotations[0].smi, wrap_tag=DocumentToken.SMILES.value
                 )
-            parts.append(body)
+
+            tabular_chart_annotations = [
+                ann
+                for ann in item.annotations
+                if isinstance(ann, PictureTabularChartData)
+            ]
+            if len(tabular_chart_annotations) > 0:
+                temp_doc = DoclingDocument(name="temp")
+                temp_table = temp_doc.add_table(
+                    data=tabular_chart_annotations[0].chart_data
+                )
+                otsl_content = temp_table.export_to_otsl(
+                    temp_doc, add_cell_location=False
+                )
+                body += otsl_content
+            res_parts.append(create_ser_result(text=body, span_source=item))
 
         if params.add_caption:
-            cap_text = doc_serializer.serialize_captions(item=item, **kwargs).text
-            if cap_text:
-                parts.append(cap_text)
+            cap_res = doc_serializer.serialize_captions(item=item, **kwargs)
+            if cap_res.text:
+                res_parts.append(cap_res)
 
-        text_res = "".join(parts)
+        text_res = "".join([r.text for r in res_parts])
         if text_res:
             token = DocumentToken.create_token_name_from_doc_item_label(
-                label=item.label
+                label=DocItemLabel.CHART if is_chart else DocItemLabel.PICTURE,
             )
             text_res = _wrap(text=text_res, wrap_tag=token)
-        return SerializationResult(text=text_res)
+        return create_ser_result(text=text_res, span_source=res_parts)
 
 
 class DocTagsKeyValueSerializer(BaseKeyValueSerializer):
@@ -256,8 +288,8 @@ class DocTagsKeyValueSerializer(BaseKeyValueSerializer):
     ) -> SerializationResult:
         """Serializes the passed item."""
         params = DocTagsParams(**kwargs)
-
         body = ""
+        results: list[SerializationResult] = []
 
         page_no = 1
         if len(item.prov) > 0:
@@ -302,14 +334,16 @@ class DocTagsKeyValueSerializer(BaseKeyValueSerializer):
             tok = f"{cell.label.value}_{cell.cell_id}"
             cell_txt = _wrap(text=cell_txt, wrap_tag=tok)
             body += cell_txt
+        results.append(create_ser_result(text=body, span_source=item))
 
         if params.add_caption:
-            cap_text = doc_serializer.serialize_captions(item=item, **kwargs).text
-            if cap_text:
-                body += cap_text
+            cap_res = doc_serializer.serialize_captions(item=item, **kwargs)
+            if cap_res.text:
+                results.append(cap_res)
 
+        body = "".join([r.text for r in results])
         body = _wrap(body, DocumentToken.KEY_VALUE_REGION.value)
-        return SerializationResult(text=body)
+        return create_ser_result(text=body, span_source=results)
 
 
 class DocTagsFormSerializer(BaseFormSerializer):
@@ -326,8 +360,7 @@ class DocTagsFormSerializer(BaseFormSerializer):
     ) -> SerializationResult:
         """Serializes the passed item."""
         # TODO add actual implementation
-        text_res = ""
-        return SerializationResult(text=text_res)
+        return create_ser_result()
 
 
 class DocTagsListSerializer(BaseModel, BaseListSerializer):
@@ -348,7 +381,7 @@ class DocTagsListSerializer(BaseModel, BaseListSerializer):
         **kwargs,
     ) -> SerializationResult:
         """Serializes the passed item."""
-        my_visited = visited or set()
+        my_visited = visited if visited is not None else set()
         params = DocTagsParams(**kwargs)
         parts = doc_serializer.get_parts(
             item=item,
@@ -361,8 +394,9 @@ class DocTagsListSerializer(BaseModel, BaseListSerializer):
         if parts:
             text_res = delim.join(
                 [
-                    _wrap(text=p.text, wrap_tag=DocumentToken.LIST_ITEM.value)
+                    t
                     for p in parts
+                    if (t := _wrap(text=p.text, wrap_tag=DocumentToken.LIST_ITEM.value))
                 ]
             )
             text_res = f"{text_res}{delim}"
@@ -374,7 +408,7 @@ class DocTagsListSerializer(BaseModel, BaseListSerializer):
             text_res = _wrap(text=text_res, wrap_tag=wrap_tag)
         else:
             text_res = ""
-        return SerializationResult(text=text_res)
+        return create_ser_result(text=text_res, span_source=parts)
 
 
 class DocTagsInlineSerializer(BaseInlineSerializer):
@@ -392,7 +426,7 @@ class DocTagsInlineSerializer(BaseInlineSerializer):
         **kwargs,
     ) -> SerializationResult:
         """Serializes the passed item."""
-        my_visited = visited or set()
+        my_visited = visited if visited is not None else set()
         params = DocTagsParams(**kwargs)
         parts = doc_serializer.get_parts(
             item=item,
@@ -407,7 +441,7 @@ class DocTagsInlineSerializer(BaseInlineSerializer):
         if text_res:
             text_res = f"{text_res}{delim}"
             text_res = _wrap(text=text_res, wrap_tag=wrap_tag)
-        return SerializationResult(text=text_res)
+        return create_ser_result(text=text_res, span_source=parts)
 
 
 class DocTagsFallbackSerializer(BaseFallbackSerializer):
@@ -423,8 +457,7 @@ class DocTagsFallbackSerializer(BaseFallbackSerializer):
         **kwargs,
     ) -> SerializationResult:
         """Serializes the passed item."""
-        text_res = ""
-        return SerializationResult(text=text_res)
+        return create_ser_result()
 
 
 class DocTagsDocSerializer(DocSerializer):
@@ -443,24 +476,28 @@ class DocTagsDocSerializer(DocSerializer):
     params: DocTagsParams = DocTagsParams()
 
     @override
-    def serialize_page(self, parts: list[SerializationResult]) -> SerializationResult:
+    def serialize_page(
+        self, *, parts: list[SerializationResult], **kwargs
+    ) -> SerializationResult:
         """Serialize a page out of its parts."""
         delim = _get_delim(params=self.params)
-        text_res = delim.join([p.text for p in parts])
-        return SerializationResult(text=text_res)
+        text_res = delim.join([p.text for p in parts if p.text])
+        return create_ser_result(text=text_res, span_source=parts)
 
     @override
-    def serialize_doc(self, pages: list[SerializationResult]) -> SerializationResult:
+    def serialize_doc(
+        self, *, pages: dict[Optional[int], SerializationResult], **kwargs
+    ) -> SerializationResult:
         """Serialize a document out of its pages."""
         delim = _get_delim(params=self.params)
         if self.params.add_page_break:
             page_sep = f"{delim}<{DocumentToken.PAGE_BREAK.value}>{delim}"
-            content = page_sep.join([p.text for p in pages if p.text])
+            content = page_sep.join([text for k in pages if (text := pages[k].text)])
         else:
-            content = self.serialize_page(parts=pages).text
+            content = self.serialize_page(parts=list(pages.values())).text
         wrap_tag = DocumentToken.DOCUMENT.value
         text_res = f"<{wrap_tag}>{content}{delim}</{wrap_tag}>"
-        return SerializationResult(text=text_res)
+        return create_ser_result(text=text_res, span_source=list(pages.values()))
 
     @override
     def serialize_captions(
@@ -470,11 +507,10 @@ class DocTagsDocSerializer(DocSerializer):
     ) -> SerializationResult:
         """Serialize the item's captions."""
         params = DocTagsParams(**kwargs)
-        parts: list[str] = []
-
+        results: list[SerializationResult] = []
         if item.captions:
-            cap_text = super().serialize_captions(item, **kwargs).text
-            if cap_text:
+            cap_res = super().serialize_captions(item, **kwargs)
+            if cap_res.text:
                 if params.add_location:
                     for caption in item.captions:
                         if caption.cref not in self.get_excluded_refs(**kwargs):
@@ -484,9 +520,9 @@ class DocTagsDocSerializer(DocSerializer):
                                     xsize=params.xsize,
                                     ysize=params.ysize,
                                 )
-                                parts.append(loc_txt)
-                parts.append(cap_text)
-        text_res = "".join(parts)
+                                results.append(create_ser_result(text=loc_txt))
+                results.append(cap_res)
+        text_res = "".join([r.text for r in results])
         if text_res:
             text_res = _wrap(text=text_res, wrap_tag=DocumentToken.CAPTION.value)
-        return SerializationResult(text=text_res)
+        return create_ser_result(text=text_res, span_source=results)