Merge branch 'main' of github.com:DS4SD/docling into cau/od-and-image-classifier-api-facet

cau-git · cau-git · commit 7bfa2c8c6a6f · 2026-02-17T12:43:25.000+01:00
diff --git a/docling/datamodel/pipeline_options.py b/docling/datamodel/pipeline_options.py
@@ -10,6 +10,7 @@
     BaseModel,
     ConfigDict,
     Field,
+    field_validator,
 )
 from typing_extensions import deprecated
 
@@ -58,6 +59,10 @@
     SMOLDOCLING_TRANSFORMERS as smoldocling_vlm_conversion_options,
     VlmModelType,
 )
+from docling.models.inference_engines.object_detection.base import (
+    ObjectDetectionEngineOptionsMixin,
+)
+from docling.models.inference_engines.vlm.base import VlmEngineOptionsMixin
 
 _log = logging.getLogger(__name__)
 
@@ -639,7 +644,7 @@ def repo_cache_folder(self) -> str:
 
 
 class PictureDescriptionVlmEngineOptions(
-    StagePresetMixin, PictureDescriptionBaseOptions
+    StagePresetMixin, VlmEngineOptionsMixin, PictureDescriptionBaseOptions
 ):
     """Configuration for VLM runtime-based picture description.
 
@@ -667,9 +672,6 @@ class PictureDescriptionVlmEngineOptions(
     model_spec: VlmModelSpec = Field(
         description="Model specification with runtime-specific overrides"
     )
-    engine_options: BaseVlmEngineOptions = Field(
-        description="Runtime configuration (transformers, mlx, api, etc.)"
-    )
     prompt: Annotated[
         str,
         Field(
@@ -715,7 +717,7 @@ class PictureDescriptionVlmEngineOptions(
 """
 
 
-class VlmConvertOptions(StagePresetMixin, BaseModel):
+class VlmConvertOptions(StagePresetMixin, VlmEngineOptionsMixin, BaseModel):
     """Configuration for VLM-based document conversion.
 
     This stage uses vision-language models to convert document pages to
@@ -738,10 +740,6 @@ class VlmConvertOptions(StagePresetMixin, BaseModel):
         description="Model specification with runtime-specific overrides"
     )
 
-    engine_options: BaseVlmEngineOptions = Field(
-        description="Runtime configuration (transformers, mlx, api, etc.)"
-    )
-
     scale: float = Field(
         default=2.0, description="Image scaling factor for preprocessing"
     )
@@ -759,7 +757,7 @@ class VlmConvertOptions(StagePresetMixin, BaseModel):
     )
 
 
-class CodeFormulaVlmOptions(StagePresetMixin, BaseModel):
+class CodeFormulaVlmOptions(StagePresetMixin, VlmEngineOptionsMixin, BaseModel):
     """Configuration for VLM-based code and formula extraction.
 
     This stage uses vision-language models to extract code blocks and
@@ -778,10 +776,6 @@ class CodeFormulaVlmOptions(StagePresetMixin, BaseModel):
         description="Model specification with runtime-specific overrides"
     )
 
-    engine_options: BaseVlmEngineOptions = Field(
-        description="Runtime configuration (transformers, mlx, api, etc.)"
-    )
-
     scale: float = Field(
         default=2.0, description="Image scaling factor for preprocessing"
     )
@@ -1119,7 +1113,11 @@ class LayoutOptions(BaseLayoutOptions):
     ] = DOCLING_LAYOUT_HERON
 
 
-class LayoutObjectDetectionOptions(ObjectDetectionStagePresetMixin, BaseLayoutOptions):
+class LayoutObjectDetectionOptions(
+    ObjectDetectionStagePresetMixin,
+    ObjectDetectionEngineOptionsMixin,
+    BaseLayoutOptions,
+):
     """Options for layout detection using object-detection runtimes."""
 
     kind: ClassVar[str] = "layout_object_detection"
@@ -1141,10 +1139,6 @@ class LayoutObjectDetectionOptions(ObjectDetectionStagePresetMixin, BaseLayoutOp
         description="Object-detection model specification for layout analysis",
     )
 
-    engine_options: BaseObjectDetectionEngineOptions = Field(
-        description="Runtime configuration for the object-detection engine",
-    )
-
 
 LayoutObjectDetectionOptions.register_preset(
     stage_model_specs.OBJECT_DETECTION_LAYOUT_HERON
diff --git a/docling/models/inference_engines/object_detection/base.py b/docling/models/inference_engines/object_detection/base.py
@@ -5,10 +5,22 @@
 import logging
 from abc import ABC, abstractmethod
 from enum import Enum
-from typing import TYPE_CHECKING, Any, Dict, List, Optional
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    ClassVar,
+    Dict,
+    List,
+    Literal,
+    Optional,
+    Type,
+    get_args,
+    get_origin,
+)
 
 from PIL.Image import Image
-from pydantic import BaseModel, ConfigDict, Field
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+from pydantic_core import PydanticUndefined
 
 if TYPE_CHECKING:
     from docling.datamodel.stage_model_specs import EngineModelConfig
@@ -43,6 +55,61 @@ class BaseObjectDetectionEngineOptions(BaseModel):
         description="Minimum confidence score to keep a detection (0.0 to 1.0)",
     )
 
+    _registry: ClassVar[
+        dict[ObjectDetectionEngineType, Type[BaseObjectDetectionEngineOptions]]
+    ] = {}
+
+    @classmethod
+    def __pydantic_init_subclass__(cls, **kwargs):
+        super().__pydantic_init_subclass__(**kwargs)
+
+        # Skip base class itself
+        if cls is BaseObjectDetectionEngineOptions:
+            return
+
+        # only register concrete subclasses that fix engine_type via Literal
+        field = cls.model_fields.get("engine_type")
+        if not field:
+            return
+
+        engine_type = None
+
+        # 1. Literal[...] annotation
+        ann = field.annotation
+        if get_origin(ann) is Literal:
+            values = get_args(ann)
+            if len(values) == 1:
+                engine_type = values[0]
+
+        # 2. Explicit default
+        if engine_type is None and field.default is not PydanticUndefined:
+            engine_type = field.default
+
+        if engine_type is not None:
+            BaseObjectDetectionEngineOptions._registry[engine_type] = cls
+
+
+class ObjectDetectionEngineOptionsMixin(BaseModel):
+    engine_options: BaseObjectDetectionEngineOptions = Field(
+        description="Runtime configuration for the object-detection engine",
+    )
+
+    @field_validator("engine_options", mode="before")
+    @classmethod
+    def resolve_engine_options(cls, value):
+        # already concrete
+        if isinstance(value, BaseObjectDetectionEngineOptions):
+            return value
+
+        # dict / JSON case
+        if isinstance(value, dict):
+            engine_type = value.get("engine_type")
+            model_cls = BaseObjectDetectionEngineOptions._registry.get(engine_type)
+            if model_cls:
+                return model_cls.model_validate(value)
+
+        return value
+
 
 class ObjectDetectionEngineInput(BaseModel):
     """Generic input accepted by every object-detection engine."""
diff --git a/docling/models/inference_engines/vlm/base.py b/docling/models/inference_engines/vlm/base.py
@@ -3,10 +3,22 @@
 import logging
 from abc import ABC, abstractmethod
 from enum import Enum
-from typing import TYPE_CHECKING, Any, Dict, List, Optional
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    ClassVar,
+    Dict,
+    List,
+    Literal,
+    Optional,
+    Type,
+    get_args,
+    get_origin,
+)
 
 from PIL.Image import Image
-from pydantic import BaseModel, ConfigDict, Field
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+from pydantic_core import PydanticUndefined
 
 if TYPE_CHECKING:
     from docling.datamodel.stage_model_specs import EngineModelConfig
@@ -62,6 +74,60 @@ class BaseVlmEngineOptions(BaseModel):
 
     engine_type: VlmEngineType = Field(description="Type of inference engine to use")
 
+    # registry: engine_type → subclass
+    _registry: ClassVar[Dict[VlmEngineType, Type["BaseVlmEngineOptions"]]] = {}
+
+    @classmethod
+    def __pydantic_init_subclass__(cls, **kwargs):
+        super().__pydantic_init_subclass__(**kwargs)
+
+        # Skip base class itself
+        if cls is BaseVlmEngineOptions:
+            return
+
+        # only register concrete subclasses that fix engine_type via Literal
+        field = cls.model_fields.get("engine_type")
+        if not field:
+            return
+
+        engine_type = None
+
+        # 1. Literal[...] annotation
+        ann = field.annotation
+        if get_origin(ann) is Literal:
+            values = get_args(ann)
+            if len(values) == 1:
+                engine_type = values[0]
+
+        # 2. Explicit default
+        if engine_type is None and field.default is not PydanticUndefined:
+            engine_type = field.default
+
+        if engine_type is not None:
+            BaseVlmEngineOptions._registry[engine_type] = cls
+
+
+class VlmEngineOptionsMixin(BaseModel):
+    engine_options: BaseVlmEngineOptions = Field(
+        description="Runtime configuration (transformers, mlx, api, etc.)"
+    )
+
+    @field_validator("engine_options", mode="before")
+    @classmethod
+    def resolve_engine_options(cls, value):
+        # already concrete
+        if isinstance(value, BaseVlmEngineOptions):
+            return value
+
+        # dict / JSON case
+        if isinstance(value, dict):
+            engine_type = value.get("engine_type")
+            model_cls = BaseVlmEngineOptions._registry.get(engine_type)
+            if model_cls:
+                return model_cls.model_validate(value)
+
+        return value
+
 
 class VlmEngineInput(BaseModel):
     """Input to a VLM inference engine.
