update Markdown serialization

Signed-off-by: Panos Vagenas <[email protected]>

Author: vagenas

docling_core/transforms/serializer/base.py

@@ -9,6 +9,7 @@
 from typing import Any, Optional, Union
 
 from pydantic import AnyUrl, BaseModel
+from typing_extensions import deprecated
 
 from docling_core.types.doc.document import (
     DocItem,
@@ -258,6 +259,7 @@ def serialize_captions(
         """Serialize the item's captions."""
         ...
 
+    @deprecated("Use serialize_meta() instead.")
     @abstractmethod
     def serialize_annotations(
         self,
@@ -267,6 +269,15 @@ def serialize_annotations(
         """Serialize the item's annotations."""
         ...
 
+    @abstractmethod
+    def serialize_meta(
+        self,
+        item: NodeItem,
+        **kwargs: Any,
+    ) -> SerializationResult:
+        """Serialize the item's meta."""
+        ...
+
     @abstractmethod
     def get_excluded_refs(self, **kwargs: Any) -> set[str]:
         """Get references to excluded items."""
@@ -287,6 +298,26 @@ def get_serializer(self, doc: DoclingDocument) -> BaseDocSerializer:
         ...
 
 
+class BaseMetaSerializer(ABC):
+    """Base class for meta serializers."""
+
+    @abstractmethod
+    def serialize(
+        self,
+        *,
+        item: NodeItem,
+        doc: DoclingDocument,
+        **kwargs: Any,
+    ) -> SerializationResult:
+        """Serializes the meta of the passed item."""
+        ...
+
+    def _humanize_text(self, text: str, title: bool = False) -> str:
+        tmp = text.replace("__", "_").replace("_", " ")
+        return tmp.title() if title else tmp.capitalize()
+
+
+@deprecated("Use BaseMetaSerializer() instead.")
 class BaseAnnotationSerializer(ABC):
     """Base class for annotation serializers."""
 

docling_core/transforms/serializer/common.py

@@ -4,6 +4,7 @@
 #
 
 """Define base classes for serialization."""
+import logging
 import re
 import sys
 from abc import abstractmethod
@@ -22,6 +23,7 @@
     BaseInlineSerializer,
     BaseKeyValueSerializer,
     BaseListSerializer,
+    BaseMetaSerializer,
     BasePictureSerializer,
     BaseTableSerializer,
     BaseTextSerializer,
@@ -56,6 +58,9 @@
 _DEFAULT_LAYERS = {cl for cl in ContentLayer}
 
 
+_logger = logging.getLogger(__name__)
+
+
 class _PageBreakNode(NodeItem):
     """Page break node."""
 
@@ -215,6 +220,7 @@ class DocSerializer(BaseModel, BaseDocSerializer):
     list_serializer: BaseListSerializer
     inline_serializer: BaseInlineSerializer
 
+    meta_serializer: Optional[BaseMetaSerializer] = None
     annotation_serializer: BaseAnnotationSerializer
 
     params: CommonParams = CommonParams()
@@ -435,6 +441,13 @@ def get_parts(
             )
             if part.text:
                 parts.append(part)
+
+            part = self.serialize_meta(
+                item=node,
+                **kwargs,
+            )
+            if part.text:
+                parts.append(part)
         return parts
 
     @override
@@ -528,6 +541,30 @@ def serialize_captions(
             text_res = ""
         return create_ser_result(text=text_res, span_source=results)
 
+    @override
+    def serialize_meta(
+        self,
+        item: NodeItem,
+        **kwargs: Any,
+    ) -> SerializationResult:
+        """Serialize the item's meta."""
+        if self.meta_serializer:
+            return self.meta_serializer.serialize(
+                item=item,
+                doc=self.doc,
+                **kwargs,
+            )
+        else:
+            _logger.warning("No meta serializer found.")
+            return create_ser_result(
+                text="", span_source=item if isinstance(item, DocItem) else []
+            )
+        # return create_ser_result(
+        #     text=item.meta.model_dump_json() if item.meta else "",
+        #     span_source=item,
+        # )
+
+    # TODO deprecate
     @override
     def serialize_annotations(
         self,

docling_core/transforms/serializer/markdown.py

@@ -11,7 +11,7 @@
 from pathlib import Path
 from typing import Any, Optional, Union
 
-from pydantic import AnyUrl, BaseModel, PositiveInt
+from pydantic import AnyUrl, BaseModel, Field, PositiveInt
 from tabulate import tabulate
 from typing_extensions import override
 
@@ -23,6 +23,7 @@
     BaseInlineSerializer,
     BaseKeyValueSerializer,
     BaseListSerializer,
+    BaseMetaSerializer,
     BasePictureSerializer,
     BaseTableSerializer,
     BaseTextSerializer,
@@ -36,6 +37,7 @@
 )
 from docling_core.types.doc.base import ImageRefMode
 from docling_core.types.doc.document import (
+    BaseMeta,
     CodeItem,
     ContentLayer,
     DescriptionAnnotation,
@@ -52,14 +54,18 @@
     KeyValueItem,
     ListGroup,
     ListItem,
+    MoleculeMetaField,
     NodeItem,
     PictureClassificationData,
+    PictureClassificationMetaField,
     PictureItem,
     PictureMoleculeData,
     PictureTabularChartData,
     RichTableCell,
     SectionHeaderItem,
+    SummaryMetaField,
     TableItem,
+    TabularChartMetaField,
     TextItem,
     TitleItem,
 )
@@ -102,8 +108,18 @@ class MarkdownParams(CommonParams):
     page_break_placeholder: Optional[str] = None  # e.g. "<!-- page break -->"
     escape_underscores: bool = True
     escape_html: bool = True
-    include_annotations: bool = True
-    mark_annotations: bool = False
+    include_meta: bool = Field(default=True, description="Include item meta.")
+    mark_meta: bool = Field(default=False, description="Mark meta sections.")
+    include_annotations: bool = Field(
+        default=True,
+        description="Include item annotations.",
+        deprecated="Use include_meta instead.",
+    )
+    mark_annotations: bool = Field(
+        default=False,
+        description="Mark annotation sections.",
+        deprecated="Use mark_meta instead.",
+    )
     orig_list_item_marker_mode: OrigListItemMarkerMode = OrigListItemMarkerMode.AUTO
     ensure_valid_list_item_marker: bool = True
 
@@ -245,9 +261,67 @@ def serialize(
         return create_ser_result(text=text, span_source=res_parts)
 
 
+class MarkdownMetaSerializer(BaseModel, BaseMetaSerializer):
+    """Markdown-specific meta serializer."""
+
+    @override
+    def serialize(
+        self,
+        *,
+        item: NodeItem,
+        doc: DoclingDocument,
+        **kwargs: Any,
+    ) -> SerializationResult:
+        """Serialize the item's meta."""
+        params = MarkdownParams(**kwargs)
+        return create_ser_result(
+            text="\n\n".join(
+                [
+                    tmp
+                    for key in list(item.meta.__class__.model_fields)
+                    + list(item.meta.get_custom_part())
+                    if (
+                        tmp := self._serialize_meta_field(
+                            item.meta, key, params.mark_meta
+                        )
+                    )
+                    is not None
+                ]
+                if params.include_meta and item.meta
+                else []
+            ),
+            span_source=item if isinstance(item, DocItem) else [],
+        )
+
+    def _serialize_meta_field(
+        self, meta: BaseMeta, name: str, mark_meta: bool
+    ) -> Optional[str]:
+        if (field_val := getattr(meta, name)) is not None:
+            # NOTE: currently only considering field type, not field name
+            if isinstance(field_val, SummaryMetaField):
+                txt = field_val.text
+            elif isinstance(field_val, PictureClassificationMetaField):
+                txt = self._humanize_text(field_val.get_main_prediction().class_name)
+            elif isinstance(field_val, MoleculeMetaField):
+                txt = field_val.smi
+            elif isinstance(field_val, TabularChartMetaField):
+                # suppressing tabular chart serialization
+                return None
+            elif tmp := str(field_val or ""):
+                txt = tmp
+            else:
+                return None
+            return (
+                f"[{self._humanize_text(name, title=True)}] {txt}" if mark_meta else txt
+            )
+        else:
+            return None
+
+
 class MarkdownAnnotationSerializer(BaseModel, BaseAnnotationSerializer):
     """Markdown-specific annotation serializer."""
 
+    @override
     def serialize(
         self,
         *,
@@ -629,6 +703,7 @@ class MarkdownDocSerializer(DocSerializer):
     list_serializer: BaseListSerializer = MarkdownListSerializer()
     inline_serializer: BaseInlineSerializer = MarkdownInlineSerializer()
 
+    meta_serializer: BaseMetaSerializer = MarkdownMetaSerializer()
     annotation_serializer: BaseAnnotationSerializer = MarkdownAnnotationSerializer()
 
     params: MarkdownParams = MarkdownParams()

docling_core/types/doc/document.py

@@ -4685,6 +4685,10 @@ def save_as_markdown(
         included_content_layers: Optional[set[ContentLayer]] = None,
         page_break_placeholder: Optional[str] = None,
         include_annotations: bool = True,
+        *,
+        include_meta: bool = True,
+        mark_meta: bool = False,
+        use_legacy_annotations: bool = False,
     ):
         """Save to markdown."""
         if isinstance(filename, str):
@@ -4714,6 +4718,9 @@ def save_as_markdown(
             included_content_layers=included_content_layers,
             page_break_placeholder=page_break_placeholder,
             include_annotations=include_annotations,
+            use_legacy_annotations=use_legacy_annotations,
+            include_meta=include_meta,
+            mark_meta=mark_meta,
         )
 
         with open(filename, "w", encoding="utf-8") as fw:
@@ -4738,6 +4745,10 @@ def export_to_markdown(  # noqa: C901
         page_break_placeholder: Optional[str] = None,  # e.g. "<!-- page break -->",
         include_annotations: bool = True,
         mark_annotations: bool = False,
+        *,
+        include_meta: bool = True,
+        mark_meta: bool = False,
+        use_legacy_annotations: bool = False,
     ) -> str:
         r"""Serialize to Markdown.
 
@@ -4783,6 +4794,15 @@ def export_to_markdown(  # noqa: C901
         :param mark_annotations: bool: Whether to mark annotations in the export; only
             relevant if include_annotations is True. (Default value = False).
         :type mark_annotations: bool = False
+        :param use_legacy_annotations: bool: Whether to use legacy annotation serialization.
+            (Default value = False).
+        :type use_legacy_annotations: bool = False
+        :param include_meta: bool: Whether to include meta in the export.
+            (Default value = True).
+        :type include_meta: bool = True
+        :param mark_meta: bool: Whether to mark meta in the export; only
+            relevant if include_meta is True. (Default value = False).
+        :type mark_meta: bool = False
         :returns: The exported Markdown representation.
         :rtype: str
         """
@@ -4813,7 +4833,9 @@ def export_to_markdown(  # noqa: C901
                 indent=indent,
                 wrap_width=text_width if text_width > 0 else None,
                 page_break_placeholder=page_break_placeholder,
-                include_annotations=include_annotations,
+                include_meta=include_meta and not use_legacy_annotations,
+                mark_meta=mark_meta,
+                include_annotations=include_annotations and use_legacy_annotations,
                 mark_annotations=mark_annotations,
             ),
         )