add deprecation, add first migration

Signed-off-by: Panos Vagenas <pva@zurich.ibm.com>

Author: vagenas

docling_core/types/doc/document.py

@@ -27,6 +27,8 @@
     Field,
     FieldSerializationInfo,
     StringConstraints,
+    TypeAdapter,
+    ValidationError,
     computed_field,
     field_serializer,
     field_validator,
@@ -941,39 +943,51 @@ class ContentLayer(str, Enum):
 DEFAULT_CONTENT_LAYERS = {ContentLayer.BODY}
 
 
-class BaseMeta(BaseModel):
-    """Base class for metadata."""
+class BasePrediction(BaseModel):
+    """Prediction field."""
 
-    model_config = ConfigDict(extra="allow")
+    confidence: Optional[float] = None
+    provenance: Optional[str] = None
+    details: Optional[dict[str, Any]] = None
 
+    @field_serializer("confidence")
+    def _serialize(self, value: float, info: FieldSerializationInfo) -> float:
+        return round_pydantic_float(value, info.context, PydanticSerCtxKey.CONFID_PREC)
 
-class SummaryInstance(BaseModel):
-    """Single summary data point."""
+
+class SummaryMetaField(BasePrediction):
+    """Summary data."""
 
     text: str
-    confidence: Optional[float] = None
-    provenance: Optional[str] = None
 
 
-class SummaryModel(BaseModel):
-    """Summary data."""
+class BaseMeta(BaseModel):
+    """Base class for metadata."""
+
+    model_config = ConfigDict(extra="allow")
+    summary: Optional[SummaryMetaField] = None
+
 
-    # convention: the first instance represents the main summary
-    instances: List[SummaryInstance] = Field(default_factory=list, min_length=1)
-    # NOTE: if needed, can add validator to coerce simpler forms to instances
+class PictureClassificationPrediction(BasePrediction):
+    """Picture classification instance."""
 
+    class_name: str
 
-class CommonMeta(BaseMeta):
-    """Common metadata model."""
 
-    summary: Optional[SummaryModel] = None
+class PictureClassificationMetaField(BaseModel):
+    """Picture classification metadata field."""
+
+    predictions: list[PictureClassificationPrediction] = Field(
+        default_factory=list, min_length=1
+    )
 
 
-class PictureMeta(CommonMeta):
+class PictureMeta(BaseMeta):
     """Picture metadata model."""
 
+    classification: Optional[PictureClassificationMetaField] = None
+
     # TODO the previous classes include "kind" for disambiguation, which is not needed here
-    classification: Optional[PictureClassificationData] = None
     molecule: Optional[PictureMoleculeData] = None
     tabular_chart: Optional[PictureTabularChartData] = None
     line_chart: Optional[PictureLineChartData] = None
@@ -983,13 +997,6 @@ class PictureMeta(CommonMeta):
     scatter_chart: Optional[PictureScatterChartData] = None
 
 
-class TableMeta(CommonMeta):
-    """Table metadata model."""
-
-    # TODO the previous classes include "kind" for disambiguation, which is not needed here
-    description: Optional[DescriptionAnnotation] = None
-
-
 class NodeItem(BaseModel):
     """NodeItem."""
 
@@ -1099,7 +1106,7 @@ def _add_sibling(
 class GroupItem(NodeItem):  # Container type, can't be a leaf node
     """GroupItem."""
 
-    meta: Optional[CommonMeta] = None
+    meta: Optional[BaseMeta] = None
 
     name: str = (
         "group"  # Name of the group, e.g. "Introduction Chapter",
@@ -1151,7 +1158,7 @@ class DocItem(
 
     label: DocItemLabel
     prov: List[ProvenanceItem] = []
-    meta: Optional[CommonMeta] = None
+    meta: Optional[BaseMeta] = None
 
     def get_location_tokens(
         self,
@@ -1460,9 +1467,47 @@ class PictureItem(FloatingItem):
         DocItemLabel.PICTURE
     )
 
-    annotations: List[PictureDataType] = []
+    annotations: Annotated[
+        List[PictureDataType],
+        Field(deprecated="The `annotations` field is deprecated; use `meta` instead."),
+    ] = []
     meta: Optional[PictureMeta] = None
 
+    @model_validator(mode="before")
+    @classmethod
+    def migrate_annotations_to_meta(cls, data: Any) -> Any:
+        """Migrate the `annotations` field to `meta`."""
+        if isinstance(data, dict) and (annotations := data.get("annotations")):
+
+            for raw_ann in annotations:
+                # migrate annotations to meta
+                try:
+                    # Use Pydantic TypeAdapter to validate the annotation type according to the instruction.
+
+                    ann: PictureDataType = TypeAdapter(PictureDataType).validate_python(
+                        raw_ann
+                    )
+                    if isinstance(ann, PictureClassificationData):
+                        # ensure meta field is present
+                        data.setdefault("meta", {})
+                        data["meta"].setdefault(
+                            "classification",
+                            PictureClassificationMetaField(
+                                predictions=[
+                                    PictureClassificationPrediction(
+                                        class_name=pred.class_name,
+                                        confidence=pred.confidence,
+                                        provenance=ann.provenance,
+                                    )
+                                    for pred in ann.predicted_classes
+                                ],
+                            ).model_dump(),
+                        )
+                except ValidationError as e:
+                    raise e
+
+        return data
+
     # Convert the image to Base64
     def _image_to_base64(self, pil_image, format="PNG"):
         """Base64 representation of the image."""
@@ -1609,8 +1654,10 @@ class TableItem(FloatingItem):
         DocItemLabel.TABLE,
     ] = DocItemLabel.TABLE
 
-    annotations: List[TableAnnotationType] = []
-    meta: Optional[TableMeta] = None
+    annotations: Annotated[
+        List[TableAnnotationType],
+        deprecated("The `annotations` field is deprecated; use `meta` instead."),
+    ] = []
 
     def export_to_dataframe(
         self, doc: Optional["DoclingDocument"] = None