docling-core 2.85.0__tar.gz → 2.87.0__tar.gz

{docling_core-2.85.0 → docling_core-2.87.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: docling-core
-Version: 2.85.0
+Version: 2.87.0
 Summary: A python library to define and validate data types in Docling.
 Author-email: Cesar Berrospi Ramis <ceb@zurich.ibm.com>, Panos Vagenas <pva@zurich.ibm.com>, Michele Dolfi <dol@zurich.ibm.com>, Christoph Auer <cau@zurich.ibm.com>, Peter Staar <taa@zurich.ibm.com>
 Maintainer-email: Panos Vagenas <pva@zurich.ibm.com>, Michele Dolfi <dol@zurich.ibm.com>, Christoph Auer <cau@zurich.ibm.com>, Peter Staar <taa@zurich.ibm.com>, Cesar Berrospi Ramis <ceb@zurich.ibm.com>

{docling_core-2.85.0 → docling_core-2.87.0}/docling_core/cli/view.py

@@ -69,8 +69,7 @@ def view(
         image_mode=ImageRefMode.EMBEDDED,
         split_page_view=split_view,
     )
-    with open(target_path, "w", encoding="utf-8") as f:
-        f.write(html_output)
+    target_path.write_text(html_output, encoding="utf-8")
     webbrowser.open(url=f"file://{target_path.absolute().resolve()}")
 
 

{docling_core-2.85.0 → docling_core-2.87.0}/docling_core/transforms/visualizer/layout_visualizer.py

@@ -148,7 +148,7 @@ class LayoutVisualizer(BaseVisualizer):
         images: Optional[dict[Optional[int], Image]] = None,
         included_content_layers: Optional[set[ContentLayer]] = None,
     ):
-        """Draw the document clusters and optionaly the reading order."""
+        """Draw the document clusters and optionally the reading order."""
         clusters = []
         my_images: dict[Optional[int], Image] = {}
 

docling_core-2.87.0/docling_core/types/doc/__init__.py

@@ -0,0 +1,200 @@
+"""Package for models defined by the Document type."""
+
+from docling_core.types.doc.base import (
+    BoundingBox,
+    CoordOrigin,
+    ImageRefMode,
+    PydanticSerCtxKey,
+    Size,
+)
+from docling_core.types.doc.common.annotations import (
+    BaseAnnotation,
+    DescriptionAnnotation,
+    MiscAnnotation,
+)
+from docling_core.types.doc.common.content_layer import ContentLayer
+from docling_core.types.doc.common.formatting import (
+    Formatting,
+    Script,
+)
+from docling_core.types.doc.common.meta import (
+    BaseMeta,
+    BasePrediction,
+    CodeMetaField,
+    DescriptionMetaField,
+    EntitiesMetaField,
+    EntityMention,
+    FloatingMeta,
+    KeywordsMetaField,
+    LanguageMetaField,
+    MetaFieldName,
+    MetaUtils,
+    SummaryMetaField,
+    TopicsMetaField,
+)
+from docling_core.types.doc.common.origin import (
+    DocumentOrigin,
+)
+from docling_core.types.doc.common.reference import (
+    FineRef,
+    ImageRef,
+    PageItem,
+    ProvenanceItem,
+    RefItem,
+)
+from docling_core.types.doc.common.scalars import (
+    CharSpan,
+    LevelNumber,
+    Uint64,
+)
+from docling_core.types.doc.common.source import (
+    BaseSource,
+    SourceType,
+    TrackSource,
+)
+from docling_core.types.doc.doctags import (
+    DocTagsDocument,
+    DocTagsPage,
+)
+from docling_core.types.doc.document import DoclingDocument
+from docling_core.types.doc.items.code import CodeItem
+from docling_core.types.doc.items.content import ContentItem
+from docling_core.types.doc.items.form import (
+    FieldHeadingItem,
+    FieldItem,
+    FieldRegionItem,
+    FieldValueItem,
+)
+from docling_core.types.doc.items.group import (
+    GroupItem,
+    InlineGroup,
+    ListGroup,
+    OrderedList,
+    UnorderedList,
+)
+from docling_core.types.doc.items.key_value import (
+    FormItem,
+    GraphCell,
+    GraphData,
+    GraphLink,
+    KeyValueItem,
+)
+from docling_core.types.doc.items.node import (
+    DocItem,
+    FloatingItem,
+    NodeItem,
+)
+from docling_core.types.doc.items.picture.charts import (
+    ChartBar,
+    ChartLine,
+    ChartPoint,
+    ChartSlice,
+    ChartStackedBar,
+    PictureBarChartData,
+    PictureChartData,
+    PictureLineChartData,
+    PicturePieChartData,
+    PictureScatterChartData,
+    PictureStackedBarChartData,
+    PictureTabularChartData,
+)
+from docling_core.types.doc.items.picture.classification import (
+    PictureClassificationClass,
+    PictureClassificationData,
+)
+from docling_core.types.doc.items.picture.meta import (
+    MoleculeMetaField,
+    PictureClassificationMetaField,
+    PictureClassificationPrediction,
+    PictureMeta,
+    TabularChartMetaField,
+)
+from docling_core.types.doc.items.picture.molecule import PictureMoleculeData
+from docling_core.types.doc.items.picture.picture import (
+    BasePictureData,
+    PictureDataType,
+    PictureDescriptionData,
+    PictureItem,
+    PictureMiscData,
+)
+from docling_core.types.doc.items.table.table import (
+    TableAnnotationType,
+    TableItem,
+)
+from docling_core.types.doc.items.table.table_data import (
+    AnyTableCell,
+    Orientation,
+    RichTableCell,
+    TableCell,
+    TableData,
+)
+from docling_core.types.doc.items.text import (
+    FormulaItem,
+    ListItem,
+    SectionHeaderItem,
+    TextItem,
+    TitleItem,
+)
+from docling_core.types.doc.labels import (
+    CodeLanguageLabel,
+    DocItemLabel,
+    GraphCellLabel,
+    GraphLinkLabel,
+    GroupLabel,
+    HumanLanguageLabel,
+    PictureClassificationLabel,
+    TableCellLabel,
+)
+from docling_core.types.doc.page import (
+    BitmapResource,
+    BoundingRectangle,
+    ColorChannelValue,
+    ColorMixin,
+    ColorRGBA,
+    Coord2D,
+    OrderedElement,
+    PageGeometry,
+    PageNumber,
+    ParsedPdfDocument,
+    PdfCellRenderingMode,
+    PdfHyperlink,
+    PdfLine,
+    PdfMetaData,
+    PdfPageBoundaryType,
+    PdfPageGeometry,
+    PdfShape,
+    PdfTableOfContents,
+    PdfTextCell,
+    PdfWidget,
+    SegmentedPage,
+    SegmentedPdfPage,
+    TextCell,
+    TextCellUnit,
+    TextDirection,
+)
+from docling_core.types.doc.tokens import (
+    DocumentToken,
+    TableToken,
+)
+from docling_core.types.doc.webvtt import (
+    WebVTTCueBlock,
+    WebVTTCueBoldSpan,
+    WebVTTCueClassSpan,
+    WebVTTCueComponent,
+    WebVTTCueComponentBase,
+    WebVTTCueComponentWithTerminator,
+    WebVTTCueIdentifier,
+    WebVTTCueInternalText,
+    WebVTTCueItalicSpan,
+    WebVTTCueLanguageSpan,
+    WebVTTCueLanguageSpanStartTag,
+    WebVTTCueSpanStartTag,
+    WebVTTCueSpanStartTagAnnotated,
+    WebVTTCueTextSpan,
+    WebVTTCueTimings,
+    WebVTTCueUnderlineSpan,
+    WebVTTCueVoiceSpan,
+    WebVTTFile,
+    WebVTTLineTerminator,
+    WebVTTTimestamp,
+)

docling_core-2.87.0/docling_core/types/doc/common/__init__.py

@@ -0,0 +1 @@
+"""Shared, cross-cutting value models for the Docling document model."""

docling_core-2.87.0/docling_core/types/doc/common/annotations.py

@@ -0,0 +1,26 @@
+"""Generic annotation models shared across document items."""
+
+from typing import Any, Literal
+
+from pydantic import BaseModel
+
+
+class BaseAnnotation(BaseModel):
+    """Base class for all annotation types."""
+
+    kind: str
+
+
+class DescriptionAnnotation(BaseAnnotation):
+    """DescriptionAnnotation."""
+
+    kind: Literal["description"] = "description"
+    text: str
+    provenance: str
+
+
+class MiscAnnotation(BaseAnnotation):
+    """MiscAnnotation."""
+
+    kind: Literal["misc"] = "misc"
+    content: dict[str, Any]

docling_core-2.87.0/docling_core/types/doc/common/constants.py

@@ -0,0 +1,45 @@
+"""Document-level constants: schema version and default export label sets."""
+
+from typing import Final
+
+from docling_core.types.doc.labels import DocItemLabel
+
+CURRENT_VERSION: Final = "1.10.0"
+
+
+DEFAULT_EXPORT_LABELS = {
+    DocItemLabel.TITLE,
+    DocItemLabel.DOCUMENT_INDEX,
+    DocItemLabel.SECTION_HEADER,
+    DocItemLabel.PARAGRAPH,
+    DocItemLabel.TABLE,
+    DocItemLabel.PICTURE,
+    DocItemLabel.FORMULA,
+    DocItemLabel.CHECKBOX_UNSELECTED,
+    DocItemLabel.CHECKBOX_SELECTED,
+    DocItemLabel.TEXT,
+    DocItemLabel.LIST_ITEM,
+    DocItemLabel.CODE,
+    DocItemLabel.REFERENCE,
+    DocItemLabel.PAGE_HEADER,
+    DocItemLabel.PAGE_FOOTER,
+    DocItemLabel.KEY_VALUE_REGION,
+    DocItemLabel.EMPTY_VALUE,
+    DocItemLabel.FIELD_KEY,
+    DocItemLabel.FIELD_VALUE,
+    DocItemLabel.FIELD_HEADING,
+    DocItemLabel.FIELD_HINT,
+    DocItemLabel.MARKER,
+    DocItemLabel.HANDWRITTEN_TEXT,
+}
+
+
+DOCUMENT_TOKENS_EXPORT_LABELS = DEFAULT_EXPORT_LABELS.copy()
+DOCUMENT_TOKENS_EXPORT_LABELS.update(
+    [
+        DocItemLabel.FOOTNOTE,
+        DocItemLabel.CAPTION,
+        DocItemLabel.KEY_VALUE_REGION,
+        DocItemLabel.FORM,
+    ]
+)

docling_core-2.87.0/docling_core/types/doc/common/content_layer.py

@@ -0,0 +1,16 @@
+"""Content-layer enumeration for document nodes."""
+
+from enum import Enum
+
+
+class ContentLayer(str, Enum):
+    """ContentLayer."""
+
+    BODY = "body"  # main content of the document
+    FURNITURE = "furniture"  # eg page-headers/footers
+    BACKGROUND = "background"  # eg watermarks
+    INVISIBLE = "invisible"  # hidden or invisible text
+    NOTES = "notes"  # author/speaker notes, corrections, etc
+
+
+DEFAULT_CONTENT_LAYERS = {ContentLayer.BODY}

docling_core-2.87.0/docling_core/types/doc/common/formatting.py

@@ -0,0 +1,23 @@
+"""Text formatting models."""
+
+from enum import Enum
+
+from pydantic import BaseModel
+
+
+class Script(str, Enum):
+    """Text script position."""
+
+    BASELINE = "baseline"
+    SUB = "sub"
+    SUPER = "super"
+
+
+class Formatting(BaseModel):
+    """Formatting."""
+
+    bold: bool = False
+    italic: bool = False
+    underline: bool = False
+    strikethrough: bool = False
+    script: Script = Script.BASELINE

docling_core-2.87.0/docling_core/types/doc/common/meta.py

@@ -0,0 +1,290 @@
+"""Metadata models attached to document nodes."""
+
+from enum import Enum
+from typing import Annotated, Any, Final, Optional
+
+from pydantic import (
+    BaseModel,
+    BeforeValidator,
+    ConfigDict,
+    Field,
+    FieldSerializationInfo,
+    field_serializer,
+    model_validator,
+)
+from typing_extensions import Self
+
+from docling_core.types.base import UniqueList
+from docling_core.types.doc.base import PydanticSerCtxKey, round_pydantic_float
+from docling_core.types.doc.common.scalars import CharSpan
+from docling_core.types.doc.labels import CodeLanguageLabel, HumanLanguageLabel
+from docling_core.utils.validators import ensure_unique_list
+
+
+class _ExtraAllowingModel(BaseModel):
+    """Base model allowing extra fields."""
+
+    model_config = ConfigDict(extra="allow")
+
+    def get_custom_part(self) -> dict[str, Any]:
+        """Get the extra fields as a dictionary."""
+        return self.__pydantic_extra__ or {}
+
+    def _copy_without_extra(self) -> Self:
+        """Create a copy without the extra fields."""
+        return self.model_validate(self.model_dump(exclude=set(self.get_custom_part())))
+
+    def _check_custom_field_format(self, key: str) -> None:
+        parts = key.split(MetaUtils._META_FIELD_NAMESPACE_DELIMITER, maxsplit=1)
+        if len(parts) != 2 or (not parts[0]) or (not parts[1]):
+            raise ValueError(
+                f"Custom meta field name must be in format 'namespace__field_name' (e.g. 'my_corp__max_size'): {key}"
+            )
+
+    @model_validator(mode="after")
+    def _validate_field_names(self) -> Self:
+        extra_dict = self.get_custom_part()
+        for key in self.model_dump():
+            if key in extra_dict:
+                self._check_custom_field_format(key=key)
+            elif MetaUtils._META_FIELD_NAMESPACE_DELIMITER in key:
+                raise ValueError(f"Standard meta field name must not contain '__': {key}")
+
+        return self
+
+    def __setattr__(self, name: str, value: Any) -> None:
+        super().__setattr__(name, value)
+        if name in self.get_custom_part():
+            self._check_custom_field_format(key=name)
+
+    def set_custom_field(self, namespace: str, name: str, value: Any) -> str:
+        """Set a custom field and return the key."""
+        key = MetaUtils.create_meta_field_name(namespace=namespace, name=name)
+        setattr(self, key, value)
+        return key
+
+
+class BasePrediction(_ExtraAllowingModel):
+    """Prediction field."""
+
+    confidence: Optional[float] = Field(
+        default=None,
+        ge=0,
+        le=1,
+        description="The confidence of the prediction.",
+        examples=[0.9, 0.42],
+    )
+    created_by: Optional[str] = Field(
+        default=None,
+        description="The origin of the prediction.",
+        examples=["ibm-granite/granite-docling-258M"],
+    )
+
+    @field_serializer("confidence")
+    def _serialize(self, value: float, info: FieldSerializationInfo) -> float:
+        return round_pydantic_float(value, info.context, PydanticSerCtxKey.CONFID_PREC)
+
+
+class SummaryMetaField(BasePrediction):
+    """Summary data."""
+
+    text: str
+
+
+class LanguageMetaField(BasePrediction):
+    """Detected human language."""
+
+    code: HumanLanguageLabel
+
+
+class MetaFieldName(str, Enum):
+    """Standard meta field names attached to document nodes.
+
+    Note:
+        These enum members must be kept in sync with the fields of the `BaseMeta` class or its subclasses.
+    """
+
+    SUMMARY = "summary"
+    """A condensed natural-language summary of the content rooted at this node (e.g. a paragraph summary or section abstract)."""
+
+    LANGUAGE = "language"
+    """The detected human language of the node content, expressed as a BCP 47 code (e.g. ``"en"``, ``"de"``)."""
+
+    ENTITIES = "entities"
+    """Named entities extracted from the node text, such as persons, organisations, and locations."""
+
+    KEYWORDS = "keywords"
+    """Salient terms or short keyphrases that characterise the node content. Values are order-preserving and unique."""
+
+    TOPICS = "topics"
+    """Higher-level subject categories or thematic labels inferred for the node. Values are order-preserving and unique."""
+
+    DESCRIPTION = "description"
+    """A free-text description of the node, typically used for non-textual items such as figures and images."""
+
+    CLASSIFICATION = "classification"
+    """A classification label or category assigned to the node content (e.g. picture type, document genre)."""
+
+    MOLECULE = "molecule"
+    """Structured chemical / molecule data associated with the node."""
+
+    TABULAR_CHART = "tabular_chart"
+    """Tabular data extracted from a chart element."""
+
+
+class EntityMention(BasePrediction):
+    """Entity mention extracted from text."""
+
+    text: Annotated[
+        str,
+        Field(description="Normalized text of the entity mention."),
+    ]
+    orig: Annotated[
+        Optional[str],
+        Field(
+            description=(
+                "Exact source text extracted from the original charspan, "
+                "analogous to TextItem.orig. This may differ from 'text' when the "
+                "mention has been normalized."
+            )
+        ),
+    ] = None
+    label: Annotated[
+        Optional[str],
+        Field(description="Entity type or category."),
+    ] = None
+    charspan: Annotated[
+        Optional[CharSpan],
+        Field(description="Character span (0-indexed) of the entity mention in the source text."),
+    ] = None
+
+
+class EntitiesMetaField(_ExtraAllowingModel):
+    """Container for extracted entity mentions."""
+
+    mentions: Annotated[list[EntityMention], Field(min_length=1)]
+
+
+class KeywordsMetaField(_ExtraAllowingModel):
+    """Container for a list of unique keywords / keyphrases."""
+
+    values: Annotated[UniqueList[str], BeforeValidator(ensure_unique_list), Field(min_length=1)]
+
+
+class TopicsMetaField(_ExtraAllowingModel):
+    """Container for a list of unique topics / subjects."""
+
+    values: Annotated[UniqueList[str], BeforeValidator(ensure_unique_list), Field(min_length=1)]
+
+
+class BaseMeta(_ExtraAllowingModel):
+    """Base class for metadata."""
+
+    summary: Annotated[
+        Optional[SummaryMetaField],
+        Field(
+            description="A condensed natural-language summary of the content rooted at this node.",
+            examples=[{"text": "A short company/location statement."}],
+        ),
+    ] = None
+    language: Annotated[
+        Optional[LanguageMetaField],
+        Field(
+            description="The detected human language of the node content, expressed as a BCP 47 code.",
+            examples=[{"code": "en"}],
+        ),
+    ] = None
+    entities: Annotated[
+        Optional[EntitiesMetaField],
+        Field(
+            description=(
+                "Named entities extracted from the node text (persons, organisations, locations, etc.). "
+                "Each mention carries the entity text, an optional type label, and an optional character span."
+            ),
+            examples=[{"mentions": [{"text": "IBM", "label": "ORG", "charspan": [0, 3]}]}],
+        ),
+    ] = None
+    keywords: Annotated[
+        Optional[KeywordsMetaField],
+        Field(
+            description=(
+                "Salient terms or short keyphrases that characterise the node content. "
+                "Keywords are more specific than topics and typically correspond to individual words or "
+                "short multi-word expressions found in or closely related to the text. "
+                "Values are order-preserving and deduplicated."
+            ),
+            examples=[{"values": ["transformer", "attention mechanism", "BERT"]}],
+        ),
+    ] = None
+    topics: Annotated[
+        Optional[TopicsMetaField],
+        Field(
+            description=(
+                "Higher-level subject categories or thematic labels inferred for the node content. "
+                "Topics are broader than keywords and describe the domain or theme rather than specific terms "
+                "(e.g., 'machine learning' rather than 'gradient descent'). "
+                "Values are order-preserving and deduplicated."
+            ),
+            examples=[{"values": ["natural language processing", "computer vision"]}],
+        ),
+    ] = None
+
+    def has_content(self) -> bool:
+        """Return True if this metadata contains any meaningful content."""
+        return any(self._value_has_content(value) for value in self.model_dump(exclude_none=True).values())
+
+    @staticmethod
+    def _value_has_content(value: Any) -> bool:
+        if value is None:
+            return False
+        if isinstance(value, list):
+            return any(BaseMeta._value_has_content(v) for v in value)
+        if isinstance(value, dict):
+            return any(BaseMeta._value_has_content(v) for v in value.values())
+        if isinstance(value, BaseModel):
+            return any(BaseMeta._value_has_content(v) for v in value.model_dump(exclude_none=True).values())
+        return True
+
+
+class DescriptionMetaField(BasePrediction):
+    """Description metadata field."""
+
+    text: str
+
+
+class FloatingMeta(BaseMeta):
+    """Metadata model for floating."""
+
+    description: Optional[DescriptionMetaField] = None
+
+
+class CodeMetaField(BasePrediction):
+    """Code representation for the respective item."""
+
+    text: str  # the actual code
+    language: Optional[CodeLanguageLabel] = None
+
+
+class MetaUtils:
+    """Metadata-related utilities."""
+
+    _META_FIELD_NAMESPACE_DELIMITER: Final = "__"
+    _META_FIELD_LEGACY_NAMESPACE: Final = "docling_legacy"
+
+    @classmethod
+    def create_meta_field_name(
+        cls,
+        *,
+        namespace: str,
+        name: str,
+    ) -> str:
+        """Create a meta field name."""
+        return f"{namespace}{cls._META_FIELD_NAMESPACE_DELIMITER}{name}"
+
+    @classmethod
+    def _create_migrated_meta_field_name(
+        cls,
+        *,
+        name: str,
+    ) -> str:
+        return cls.create_meta_field_name(namespace=cls._META_FIELD_LEGACY_NAMESPACE, name=name)