chore: add deprecation flag for annotations (#3001)

* chore: add deprecation flag for annotations

Signed-off-by: Peter Staar <taa@zurich.ibm.com>

* propagated the flag

Signed-off-by: Peter Staar <taa@zurich.ibm.com>

* moved keep_deprecated_annotations to _keep_deprecated_annotations

Signed-off-by: Peter Staar <taa@zurich.ibm.com>

---------

Signed-off-by: Peter Staar <taa@zurich.ibm.com>

Author: PeterStaar-IBM

docling/datamodel/picture_classification_options.py

@@ -25,6 +25,11 @@ class DocumentPictureClassifierOptions(
 
     kind: ClassVar[str] = "document_picture_classifier"
 
+    # TODO: default should become False in a future release, and this field
+    # may be removed entirely once docling-core drops the deprecated
+    # `annotations` attribute from DoclingDocument items.
+    _keep_deprecated_annotations: bool = True
+
     model_spec: ImageClassificationModelSpec = Field(
         default_factory=lambda: stage_model_specs.IMAGE_CLASSIFICATION_DOCUMENT_FIGURE.model_spec.model_copy(
             deep=True

docling/datamodel/pipeline_options.py

@@ -464,6 +464,11 @@ class OcrMacOptions(OcrOptions):
 class PictureDescriptionBaseOptions(BaseOptions):
     """Base configuration for picture description models."""
 
+    # TODO: default should become False in a future release, and this field
+    # may be removed entirely once docling-core drops the deprecated
+    # `annotations` attribute from DoclingDocument items.
+    _keep_deprecated_annotations: bool = True
+
     batch_size: Annotated[
         int,
         Field(

docling/models/picture_description_base_model.py

@@ -89,9 +89,10 @@ def __call__(
 
         for item, output in zip(elements, outputs):
             # FIXME: annotations is deprecated, remove once all consumers use meta.classification
-            item.annotations.append(
-                PictureDescriptionData(text=output, provenance=self.provenance)
-            )
+            if self.options._keep_deprecated_annotations:
+                item.annotations.append(
+                    PictureDescriptionData(text=output, provenance=self.provenance)
+                )
 
             # Store classification in the new meta field
             if item.meta is None:

docling/models/stages/picture_classifier/document_picture_classifier.py

@@ -181,12 +181,13 @@ def __call__(
             ]
 
             # FIXME: annotations is deprecated, remove once all consumers use meta.classification
-            item.annotations.append(
-                PictureClassificationData(
-                    provenance="DocumentPictureClassifier",
-                    predicted_classes=predicted_classes,
+            if self.options._keep_deprecated_annotations:
+                item.annotations.append(
+                    PictureClassificationData(
+                        provenance="DocumentPictureClassifier",
+                        predicted_classes=predicted_classes,
+                    )
                 )
-            )
 
             # Store classification in the new meta field
             predictions = [