docling-core 2.33.0__tar.gz → 2.34.0__tar.gz

{docling_core-2.33.0 → docling_core-2.34.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docling-core
-Version: 2.33.0
+Version: 2.34.0
 Summary: A python library to define and validate data types in Docling.
 Author-email: Cesar Berrospi Ramis <ceb@zurich.ibm.com>, Panos Vagenas <pva@zurich.ibm.com>, Michele Dolfi <dol@zurich.ibm.com>, Christoph Auer <cau@zurich.ibm.com>, Peter Staar <taa@zurich.ibm.com>
 Maintainer-email: Panos Vagenas <pva@zurich.ibm.com>, Michele Dolfi <dol@zurich.ibm.com>, Christoph Auer <cau@zurich.ibm.com>, Peter Staar <taa@zurich.ibm.com>, Cesar Berrospi Ramis <ceb@zurich.ibm.com>
@@ -32,7 +32,7 @@ Requires-Dist: pandas<3.0.0,>=2.1.4
 Requires-Dist: pillow<12.0.0,>=10.0.0
 Requires-Dist: pyyaml<7.0.0,>=5.1
 Requires-Dist: typing-extensions<5.0.0,>=4.12.2
-Requires-Dist: typer<0.16.0,>=0.12.5
+Requires-Dist: typer<0.17.0,>=0.12.5
 Requires-Dist: latex2mathml<4.0.0,>=3.77.0
 Provides-Extra: chunking
 Requires-Dist: semchunk<3.0.0,>=2.2.0; extra == "chunking"

{docling_core-2.33.0 → docling_core-2.34.0}/docling_core/transforms/serializer/base.py

@@ -202,6 +202,16 @@ class BaseDocSerializer(ABC):
         """Hook for strikethrough formatting serialization."""
         ...
 
+    @abstractmethod
+    def serialize_subscript(self, text: str, **kwargs: Any) -> str:
+        """Hook for subscript formatting serialization."""
+        ...
+
+    @abstractmethod
+    def serialize_superscript(self, text: str, **kwargs: Any) -> str:
+        """Hook for superscript formatting serialization."""
+        ...
+
     @abstractmethod
     def serialize_hyperlink(
         self,
@@ -239,6 +249,15 @@ class BaseDocSerializer(ABC):
         """Serialize the item's captions."""
         ...
 
+    @abstractmethod
+    def serialize_annotations(
+        self,
+        item: DocItem,
+        **kwargs: Any,
+    ) -> SerializationResult:
+        """Serialize the item's annotations."""
+        ...
+
     @abstractmethod
     def get_excluded_refs(self, **kwargs: Any) -> set[str]:
         """Get references to excluded items."""
@@ -257,3 +276,18 @@ class BaseSerializerProvider(ABC):
     def get_serializer(self, doc: DoclingDocument) -> BaseDocSerializer:
         """Get a the associated serializer."""
         ...
+
+
+class BaseAnnotationSerializer(ABC):
+    """Base class for annotation serializers."""
+
+    @abstractmethod
+    def serialize(
+        self,
+        *,
+        item: DocItem,
+        doc: DoclingDocument,
+        **kwargs: Any,
+    ) -> SerializationResult:
+        """Serializes the passed annotation."""
+        ...

{docling_core-2.33.0 → docling_core-2.34.0}/docling_core/transforms/serializer/common.py

@@ -15,6 +15,7 @@ from pydantic import AnyUrl, BaseModel, ConfigDict, NonNegativeInt, computed_fie
 from typing_extensions import Self, override
 
 from docling_core.transforms.serializer.base import (
+    BaseAnnotationSerializer,
     BaseDocSerializer,
     BaseFallbackSerializer,
     BaseFormSerializer,
@@ -30,6 +31,7 @@ from docling_core.transforms.serializer.base import (
 from docling_core.types.doc.document import (
     DOCUMENT_TOKENS_EXPORT_LABELS,
     ContentLayer,
+    DescriptionAnnotation,
     DocItem,
     DoclingDocument,
     FloatingItem,
@@ -41,9 +43,10 @@ from docling_core.types.doc.document import (
     OrderedList,
     PictureClassificationData,
     PictureDataType,
-    PictureDescriptionData,
     PictureItem,
     PictureMoleculeData,
+    Script,
+    TableAnnotationType,
     TableItem,
     TextItem,
     UnorderedList,
@@ -122,7 +125,9 @@ def _iterate_items(
         yield item
 
 
-def _get_picture_annotation_text(annotation: PictureDataType) -> Optional[str]:
+def _get_annotation_text(
+    annotation: Union[PictureDataType, TableAnnotationType],
+) -> Optional[str]:
     result = None
     if isinstance(annotation, PictureClassificationData):
         predicted_class = (
@@ -132,7 +137,7 @@ def _get_picture_annotation_text(annotation: PictureDataType) -> Optional[str]:
         )
         if predicted_class is not None:
             result = predicted_class.replace("_", " ")
-    elif isinstance(annotation, PictureDescriptionData):
+    elif isinstance(annotation, DescriptionAnnotation):
         result = annotation.text
     elif isinstance(annotation, PictureMoleculeData):
         result = annotation.smi
@@ -211,6 +216,8 @@ class DocSerializer(BaseModel, BaseDocSerializer):
     list_serializer: BaseListSerializer
     inline_serializer: BaseInlineSerializer
 
+    annotation_serializer: BaseAnnotationSerializer
+
     params: CommonParams = CommonParams()
 
     _excluded_refs_cache: dict[str, set[str]] = {}
@@ -449,6 +456,10 @@ class DocSerializer(BaseModel, BaseDocSerializer):
                 res = self.serialize_underline(text=res)
             if formatting.strikethrough:
                 res = self.serialize_strikethrough(text=res)
+            if formatting.script == Script.SUB:
+                res = self.serialize_subscript(text=res)
+            elif formatting.script == Script.SUPER:
+                res = self.serialize_superscript(text=res)
         if params.include_hyperlinks and hyperlink:
             res = self.serialize_hyperlink(text=res, hyperlink=hyperlink)
         return res
@@ -473,6 +484,16 @@ class DocSerializer(BaseModel, BaseDocSerializer):
         """Hook for strikethrough formatting serialization."""
         return text
 
+    @override
+    def serialize_subscript(self, text: str, **kwargs: Any) -> str:
+        """Hook for subscript formatting serialization."""
+        return text
+
+    @override
+    def serialize_superscript(self, text: str, **kwargs: Any) -> str:
+        """Hook for superscript formatting serialization."""
+        return text
+
     @override
     def serialize_hyperlink(
         self,
@@ -505,6 +526,19 @@ class DocSerializer(BaseModel, BaseDocSerializer):
             text_res = ""
         return create_ser_result(text=text_res, span_source=results)
 
+    @override
+    def serialize_annotations(
+        self,
+        item: DocItem,
+        **kwargs: Any,
+    ) -> SerializationResult:
+        """Serialize the item's annotations."""
+        return self.annotation_serializer.serialize(
+            item=item,
+            doc=self.doc,
+            **kwargs,
+        )
+
     def _get_applicable_pages(self) -> Optional[list[int]]:
         pages = {
             item.prov[0].page_no: ...

{docling_core-2.33.0 → docling_core-2.34.0}/docling_core/transforms/serializer/doctags.py

@@ -7,6 +7,7 @@ from pydantic import BaseModel
 from typing_extensions import override
 
 from docling_core.transforms.serializer.base import (
+    BaseAnnotationSerializer,
     BaseDocSerializer,
     BaseFallbackSerializer,
     BaseFormSerializer,
@@ -17,12 +18,14 @@ from docling_core.transforms.serializer.base import (
     BaseTableSerializer,
     BaseTextSerializer,
     SerializationResult,
+    Span,
 )
 from docling_core.transforms.serializer.common import (
     CommonParams,
     DocSerializer,
     create_ser_result,
 )
+from docling_core.types.doc.base import BoundingBox
 from docling_core.types.doc.document import (
     CodeItem,
     DocItem,
@@ -38,6 +41,7 @@ from docling_core.types.doc.document import (
     PictureItem,
     PictureMoleculeData,
     PictureTabularChartData,
+    ProvenanceItem,
     TableItem,
     TextItem,
     UnorderedList,
@@ -414,6 +418,39 @@ class DocTagsListSerializer(BaseModel, BaseListSerializer):
 class DocTagsInlineSerializer(BaseInlineSerializer):
     """DocTags-specific inline group serializer."""
 
+    def _get_inline_location_tags(
+        self, doc: DoclingDocument, item: InlineGroup, params: DocTagsParams
+    ) -> SerializationResult:
+
+        prov: Optional[ProvenanceItem] = None
+        boxes: list[BoundingBox] = []
+        doc_items: list[DocItem] = []
+        for it, _ in doc.iterate_items(root=item):
+            if isinstance(it, DocItem):
+                for prov in it.prov:
+                    boxes.append(prov.bbox)
+                    doc_items.append(it)
+        if prov is None:
+            return create_ser_result()
+
+        bbox = BoundingBox.enclosing_bbox(boxes=boxes)
+
+        # using last seen prov as reference for page dims
+        page_w, page_h = doc.pages[prov.page_no].size.as_tuple()
+
+        loc_str = DocumentToken.get_location(
+            bbox=bbox.to_top_left_origin(page_h).as_tuple(),
+            page_w=page_w,
+            page_h=page_h,
+            xsize=params.xsize,
+            ysize=params.ysize,
+        )
+
+        return SerializationResult(
+            text=loc_str,
+            spans=[Span(item=it) for it in doc_items],
+        )
+
     @override
     def serialize(
         self,
@@ -428,12 +465,23 @@ class DocTagsInlineSerializer(BaseInlineSerializer):
         """Serializes the passed item."""
         my_visited = visited if visited is not None else set()
         params = DocTagsParams(**kwargs)
-        parts = doc_serializer.get_parts(
-            item=item,
-            list_level=list_level,
-            is_inline_scope=True,
-            visited=my_visited,
-            **kwargs,
+        parts: List[SerializationResult] = []
+        if params.add_location:
+            inline_loc_tags_ser_res = self._get_inline_location_tags(
+                doc=doc,
+                item=item,
+                params=params,
+            )
+            parts.append(inline_loc_tags_ser_res)
+            params.add_location = False  # suppress children location serialization
+        parts.extend(
+            doc_serializer.get_parts(
+                item=item,
+                list_level=list_level,
+                is_inline_scope=True,
+                visited=my_visited,
+                **{**kwargs, **params.model_dump()},
+            )
         )
         wrap_tag = DocumentToken.INLINE.value
         delim = _get_delim(params=params)
@@ -460,6 +508,15 @@ class DocTagsFallbackSerializer(BaseFallbackSerializer):
         return create_ser_result()
 
 
+class DocTagsAnnotationSerializer(BaseAnnotationSerializer):
+    """DocTags-specific annotation serializer."""
+
+    @override
+    def serialize(self, *, item: DocItem, **kwargs: Any) -> SerializationResult:
+        """Serializes the item's annotations."""
+        return create_ser_result()
+
+
 class DocTagsDocSerializer(DocSerializer):
     """DocTags-specific document serializer."""
 
@@ -473,6 +530,8 @@ class DocTagsDocSerializer(DocSerializer):
     list_serializer: BaseListSerializer = DocTagsListSerializer()
     inline_serializer: BaseInlineSerializer = DocTagsInlineSerializer()
 
+    annotation_serializer: BaseAnnotationSerializer = DocTagsAnnotationSerializer()
+
     params: DocTagsParams = DocTagsParams()
 
     @override

{docling_core-2.33.0 → docling_core-2.34.0}/docling_core/transforms/serializer/html.py

@@ -21,6 +21,7 @@ from pydantic import AnyUrl, BaseModel
 from typing_extensions import override
 
 from docling_core.transforms.serializer.base import (
+    BaseAnnotationSerializer,
     BaseDocSerializer,
     BaseFallbackSerializer,
     BaseFormSerializer,
@@ -35,7 +36,7 @@ from docling_core.transforms.serializer.base import (
 from docling_core.transforms.serializer.common import (
     CommonParams,
     DocSerializer,
-    _get_picture_annotation_text,
+    _get_annotation_text,
     create_ser_result,
 )
 from docling_core.transforms.serializer.html_styles import (
@@ -47,6 +48,7 @@ from docling_core.types.doc.base import ImageRefMode
 from docling_core.types.doc.document import (
     CodeItem,
     ContentLayer,
+    DescriptionAnnotation,
     DocItem,
     DoclingDocument,
     FloatingItem,
@@ -59,7 +61,9 @@ from docling_core.types.doc.document import (
     ListItem,
     NodeItem,
     OrderedList,
+    PictureClassificationData,
     PictureItem,
+    PictureMoleculeData,
     PictureTabularChartData,
     SectionHeaderItem,
     TableCell,
@@ -758,14 +762,7 @@ class HTMLFallbackSerializer(BaseFallbackSerializer):
     """HTML-specific fallback serializer."""
 
     @override
-    def serialize(
-        self,
-        *,
-        item: NodeItem,
-        doc_serializer: "BaseDocSerializer",
-        doc: DoclingDocument,
-        **kwargs: Any,
-    ) -> SerializationResult:
+    def serialize(self, *, item: NodeItem, **kwargs: Any) -> SerializationResult:
         """Fallback serializer for items not handled by other serializers."""
         if isinstance(item, DocItem):
             return create_ser_result(
@@ -777,6 +774,42 @@ class HTMLFallbackSerializer(BaseFallbackSerializer):
             return create_ser_result()
 
 
+class HTMLAnnotationSerializer(BaseModel, BaseAnnotationSerializer):
+    """HTML-specific annotation serializer."""
+
+    def serialize(
+        self,
+        *,
+        item: DocItem,
+        doc: DoclingDocument,
+        **kwargs: Any,
+    ) -> SerializationResult:
+        """Serializes the passed annotation to HTML format."""
+        res_parts: list[SerializationResult] = []
+        for ann in item.get_annotations():
+            if isinstance(
+                ann,
+                (PictureClassificationData, DescriptionAnnotation, PictureMoleculeData),
+            ):
+                if ann_text := _get_annotation_text(ann):
+                    text_dir = get_text_direction(ann_text)
+                    dir_str = f' dir="{text_dir}"' if text_dir == "rtl" else ""
+                    ann_ser_res = create_ser_result(
+                        text=(
+                            f'<div data-annotation-kind="{ann.kind}"{dir_str}>'
+                            f"{html.escape(ann_text)}"
+                            f"</div>"
+                        ),
+                        span_source=item,
+                    )
+                    res_parts.append(ann_ser_res)
+
+        return create_ser_result(
+            text=" ".join([r.text for r in res_parts if r.text]),
+            span_source=res_parts,
+        )
+
+
 class HTMLDocSerializer(DocSerializer):
     """HTML-specific document serializer."""
 
@@ -790,6 +823,8 @@ class HTMLDocSerializer(DocSerializer):
     list_serializer: BaseListSerializer = HTMLListSerializer()
     inline_serializer: BaseInlineSerializer = HTMLInlineSerializer()
 
+    annotation_serializer: BaseAnnotationSerializer = HTMLAnnotationSerializer()
+
     params: HTMLParams = HTMLParams()
 
     @override
@@ -812,6 +847,16 @@ class HTMLDocSerializer(DocSerializer):
         """Apply HTML-specific strikethrough serialization."""
         return f"<del>{text}</del>"
 
+    @override
+    def serialize_subscript(self, text: str, **kwargs: Any) -> str:
+        """Apply HTML-specific subscript serialization."""
+        return f"<sub>{text}</sub>"
+
+    @override
+    def serialize_superscript(self, text: str, **kwargs: Any) -> str:
+        """Apply HTML-specific superscript serialization."""
+        return f"<sup>{text}</sup>"
+
     @override
     def serialize_hyperlink(
         self,
@@ -968,20 +1013,13 @@ class HTMLDocSerializer(DocSerializer):
                     results.append(cap_ser_res)
 
         if params.include_annotations and item.self_ref not in excluded_refs:
-            if isinstance(item, PictureItem):
-                for ann in item.annotations:
-                    if ann_text := _get_picture_annotation_text(annotation=ann):
-                        text_dir = get_text_direction(ann_text)
-                        dir_str = f' dir="{text_dir}"' if text_dir == "rtl" else ""
-                        ann_ser_res = create_ser_result(
-                            text=(
-                                f'<div data-annotation-kind="{ann.kind}"{dir_str}>'
-                                f"{html.escape(ann_text)}"
-                                f"</div>"
-                            ),
-                            span_source=item,
-                        )
-                        results.append(ann_ser_res)
+            if isinstance(item, (PictureItem, TableItem)):
+                ann_res = self.serialize_annotations(
+                    item=item,
+                    **kwargs,
+                )
+                if ann_res.text:
+                    results.append(ann_res)
 
         text_res = params.caption_delim.join([r.text for r in results])
         if text_res:

{docling_core-2.33.0 → docling_core-2.34.0}/docling_core/transforms/serializer/markdown.py

@@ -15,6 +15,7 @@ from tabulate import tabulate
 from typing_extensions import override
 
 from docling_core.transforms.serializer.base import (
+    BaseAnnotationSerializer,
     BaseDocSerializer,
     BaseFallbackSerializer,
     BaseFormSerializer,
@@ -29,7 +30,7 @@ from docling_core.transforms.serializer.base import (
 from docling_core.transforms.serializer.common import (
     CommonParams,
     DocSerializer,
-    _get_picture_annotation_text,
+    _get_annotation_text,
     _PageBreakSerResult,
     create_ser_result,
 )
@@ -37,6 +38,7 @@ from docling_core.types.doc.base import ImageRefMode
 from docling_core.types.doc.document import (
     CodeItem,
     ContentLayer,
+    DescriptionAnnotation,
     DocItem,
     DoclingDocument,
     FloatingItem,
@@ -48,7 +50,9 @@ from docling_core.types.doc.document import (
     KeyValueItem,
     NodeItem,
     OrderedList,
+    PictureClassificationData,
     PictureItem,
+    PictureMoleculeData,
     PictureTabularChartData,
     SectionHeaderItem,
     TableItem,
@@ -58,6 +62,23 @@ from docling_core.types.doc.document import (
 )
 
 
+def _get_annotation_ser_result(
+    ann_kind: str, ann_text: str, mark_annotation: bool, doc_item: DocItem
+):
+    return create_ser_result(
+        text=(
+            (
+                f'<!--<annotation kind="{ann_kind}">-->'
+                f"{ann_text}"
+                f"<!--<annotation/>-->"
+            )
+            if mark_annotation
+            else ann_text
+        ),
+        span_source=doc_item,
+    )
+
+
 class MarkdownParams(CommonParams):
     """Markdown-specific serialization parameters."""
 
@@ -136,6 +157,49 @@ class MarkdownTextSerializer(BaseModel, BaseTextSerializer):
         return create_ser_result(text=text, span_source=res_parts)
 
 
+class MarkdownAnnotationSerializer(BaseModel, BaseAnnotationSerializer):
+    """Markdown-specific annotation serializer."""
+
+    def serialize(
+        self,
+        *,
+        item: DocItem,
+        doc: DoclingDocument,
+        **kwargs: Any,
+    ) -> SerializationResult:
+        """Serialize the item's annotations."""
+        params = MarkdownParams(**kwargs)
+
+        res_parts: list[SerializationResult] = []
+        for ann in item.get_annotations():
+            if isinstance(
+                ann,
+                (
+                    PictureClassificationData,
+                    DescriptionAnnotation,
+                    PictureMoleculeData,
+                ),
+            ):
+                if ann_text := _get_annotation_text(ann):
+                    ann_res = create_ser_result(
+                        text=(
+                            (
+                                f'<!--<annotation kind="{ann.kind}">-->'
+                                f"{ann_text}"
+                                f"<!--<annotation/>-->"
+                            )
+                            if params.mark_annotations
+                            else ann_text
+                        ),
+                        span_source=item,
+                    )
+                    res_parts.append(ann_res)
+        return create_ser_result(
+            text="\n\n".join([r.text for r in res_parts if r.text]),
+            span_source=item,
+        )
+
+
 class MarkdownTableSerializer(BaseTableSerializer):
     """Markdown-specific table item serializer."""
 
@@ -149,6 +213,7 @@ class MarkdownTableSerializer(BaseTableSerializer):
         **kwargs: Any,
     ) -> SerializationResult:
         """Serializes the passed item."""
+        params = MarkdownParams(**kwargs)
         res_parts: list[SerializationResult] = []
 
         cap_res = doc_serializer.serialize_captions(
@@ -159,6 +224,16 @@ class MarkdownTableSerializer(BaseTableSerializer):
             res_parts.append(cap_res)
 
         if item.self_ref not in doc_serializer.get_excluded_refs(**kwargs):
+
+            if params.include_annotations:
+
+                ann_res = doc_serializer.serialize_annotations(
+                    item=item,
+                    **kwargs,
+                )
+                if ann_res.text:
+                    res_parts.append(ann_res)
+
             rows = [
                 [
                     # make sure that md tables are not broken
@@ -214,22 +289,12 @@ class MarkdownPictureSerializer(BasePictureSerializer):
 
         if item.self_ref not in doc_serializer.get_excluded_refs(**kwargs):
             if params.include_annotations:
-
-                for ann in item.annotations:
-                    if ann_text := _get_picture_annotation_text(annotation=ann):
-                        ann_ser_res = create_ser_result(
-                            text=(
-                                (
-                                    f'<!--<annotation kind="{ann.kind}">-->'
-                                    f"{ann_text}"
-                                    f"<!--<annotation/>-->"
-                                )
-                                if params.mark_annotations
-                                else ann_text
-                            ),
-                            span_source=item,
-                        )
-                        res_parts.append(ann_ser_res)
+                ann_res = doc_serializer.serialize_annotations(
+                    item=item,
+                    **kwargs,
+                )
+                if ann_res.text:
+                    res_parts.append(ann_res)
 
             img_res = self._serialize_image_part(
                 item=item,
@@ -257,7 +322,7 @@ class MarkdownPictureSerializer(BasePictureSerializer):
                     res_parts.append(
                         create_ser_result(text=md_table_content, span_source=item)
                     )
-        text_res = "\n\n".join([r.text for r in res_parts])
+        text_res = "\n\n".join([r.text for r in res_parts if r.text])
 
         return create_ser_result(text=text_res, span_source=res_parts)
 
@@ -471,6 +536,8 @@ class MarkdownDocSerializer(DocSerializer):
     list_serializer: BaseListSerializer = MarkdownListSerializer()
     inline_serializer: BaseInlineSerializer = MarkdownInlineSerializer()
 
+    annotation_serializer: BaseAnnotationSerializer = MarkdownAnnotationSerializer()
+
     params: MarkdownParams = MarkdownParams()
 
     @override