feat: extend and expose float serialization control (#353)

* feat: add confidence precision control to page text cells

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

* make controls public

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

---------

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

Author: vagenas

docling_core/types/doc/base.py

@@ -1,7 +1,7 @@
 """Models for the base data types."""
 
 from enum import Enum
-from typing import List, Tuple
+from typing import Any, List, Tuple
 
 from pydantic import BaseModel, FieldSerializationInfo, field_serializer
 
@@ -21,16 +21,23 @@ class CoordOrigin(str, Enum):
     BOTTOMLEFT = "BOTTOMLEFT"
 
 
-_CTX_COORD_PREC = "coord_prec"
+class PydanticSerCtxKey(str, Enum):
+    """Pydantic serialization context keys."""
 
+    COORD_PREC = "coord_prec"  # key for coordinates precision
+    CONFID_PREC = "confid_prec"  # key for confidence values precision
 
-def _serialize_precision(
-    value: float, info: FieldSerializationInfo, ctx_key: str
+
+def round_pydantic_float(
+    val: float, ctx: Any, precision_ctx_key: PydanticSerCtxKey
 ) -> float:
-    precision = info.context.get(ctx_key) if info.context else None
-    if isinstance(precision, int):
-        return round(value, precision)
-    return value
+    """Round float, provided the precision is available in the context."""
+    precision = (
+        ctx.get(precision_ctx_key.value)
+        if isinstance(ctx, dict)
+        else getattr(ctx, precision_ctx_key.value, None)
+    )
+    return round(val, precision) if isinstance(precision, int) else val
 
 
 class Size(BaseModel):
@@ -41,7 +48,7 @@ class Size(BaseModel):
 
     @field_serializer("width", "height")
     def _serialize(self, value: float, info: FieldSerializationInfo) -> float:
-        return _serialize_precision(value, info, _CTX_COORD_PREC)
+        return round_pydantic_float(value, info.context, PydanticSerCtxKey.COORD_PREC)
 
     def as_tuple(self):
         """as_tuple."""
@@ -70,7 +77,7 @@ def height(self):
 
     @field_serializer("l", "t", "r", "b")
     def _serialize(self, value: float, info: FieldSerializationInfo) -> float:
-        return _serialize_precision(value, info, _CTX_COORD_PREC)
+        return round_pydantic_float(value, info.context, PydanticSerCtxKey.COORD_PREC)
 
     def resize_by_scale(self, x_scale: float, y_scale: float):
         """resize_by_scale."""

docling_core/types/doc/document.py

@@ -41,10 +41,10 @@
 from docling_core.types.base import _JSON_POINTER_REGEX
 from docling_core.types.doc import BoundingBox, Size
 from docling_core.types.doc.base import (
-    _CTX_COORD_PREC,
     CoordOrigin,
     ImageRefMode,
-    _serialize_precision,
+    PydanticSerCtxKey,
+    round_pydantic_float,
 )
 from docling_core.types.doc.labels import (
     CodeLanguageLabel,
@@ -92,8 +92,6 @@
     ]
 )
 
-_CTX_CONFID_PREC = "confid_prec"
-
 
 class BaseAnnotation(BaseModel):
     """Base class for all annotation types."""
@@ -109,7 +107,7 @@ class PictureClassificationClass(BaseModel):
 
     @field_serializer("confidence")
     def _serialize(self, value: float, info: FieldSerializationInfo) -> float:
-        return _serialize_precision(value, info, _CTX_CONFID_PREC)
+        return round_pydantic_float(value, info.context, PydanticSerCtxKey.CONFID_PREC)
 
 
 class PictureClassificationData(BaseAnnotation):
@@ -140,7 +138,7 @@ class PictureMoleculeData(BaseAnnotation):
 
     @field_serializer("confidence")
     def _serialize(self, value: float, info: FieldSerializationInfo) -> float:
-        return _serialize_precision(value, info, _CTX_CONFID_PREC)
+        return round_pydantic_float(value, info.context, PydanticSerCtxKey.CONFID_PREC)
 
 
 class MiscAnnotation(BaseAnnotation):
@@ -4292,9 +4290,9 @@ def export_to_dict(
         """Export to dict."""
         context = {}
         if coord_precision is not None:
-            context[_CTX_COORD_PREC] = coord_precision
+            context[PydanticSerCtxKey.COORD_PREC.value] = coord_precision
         if confid_precision is not None:
-            context[_CTX_CONFID_PREC] = confid_precision
+            context[PydanticSerCtxKey.CONFID_PREC.value] = confid_precision
         out = self.model_dump(
             mode=mode, by_alias=by_alias, exclude_none=exclude_none, context=context
         )

docling_core/types/doc/page.py

@@ -35,10 +35,10 @@
 )
 
 from docling_core.types.doc.base import (
-    _CTX_COORD_PREC,
     BoundingBox,
     CoordOrigin,
-    _serialize_precision,
+    PydanticSerCtxKey,
+    round_pydantic_float,
 )
 from docling_core.types.doc.document import ImageRef
 
@@ -119,7 +119,7 @@ class BoundingRectangle(BaseModel):
 
     @field_serializer("r_x0", "r_y0", "r_x1", "r_y1", "r_x2", "r_y2", "r_x3", "r_y3")
     def _serialize(self, value: float, info: FieldSerializationInfo) -> float:
-        return _serialize_precision(value, info, _CTX_COORD_PREC)
+        return round_pydantic_float(value, info.context, PydanticSerCtxKey.COORD_PREC)
 
     @property
     def width(self) -> float:
@@ -290,6 +290,10 @@ class TextCell(ColorMixin, OrderedElement):
     confidence: float = 1.0
     from_ocr: bool
 
+    @field_serializer("confidence")
+    def _serialize(self, value: float, info: FieldSerializationInfo) -> float:
+        return round_pydantic_float(value, info.context, PydanticSerCtxKey.CONFID_PREC)
+
     def to_bounding_box(self) -> BoundingBox:
         """Convert the cell rectangle to a BoundingBox."""
         return self.rect.to_bounding_box()