fix: fix document re-indexing (#510)

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

Author: vagenas

docling_core/types/doc/document.py

@@ -6185,6 +6185,10 @@ def index(self, doc: "DoclingDocument", page_nrs: Optional[set[int]] = None) ->
 
             self._names.append(doc.name)
 
+            # record starting indices so post-processing only touches new items
+            post_processing_keys = ["texts", "pictures", "tables", "key_value_items", "form_items"]
+            start_indices = {k: len(self.get_item_list(k)) for k in post_processing_keys}
+
             # collect items in traversal order
             for item, _ in doc._iterate_items_with_stack(
                 with_groups=True,
@@ -6242,13 +6246,6 @@ def index(self, doc: "DoclingDocument", page_nrs: Optional[set[int]] = None) ->
                             parent_index = int(parent_index_str)
                             parent_item = self.get_item_list(parent_key)[parent_index]
 
-                            # update captions field (not possible in iterate_items order):
-                            if isinstance(parent_item, FloatingItem):
-                                for cap_it, cap in enumerate(parent_item.captions):
-                                    if cap.cref == item.self_ref:
-                                        parent_item.captions[cap_it] = RefItem(cref=new_cref)
-                                        break
-
                             # update rich table cells references:
                             if isinstance(parent_item, TableItem):
                                 for cell in parent_item.data.table_cells:
@@ -6262,6 +6259,26 @@ def index(self, doc: "DoclingDocument", page_nrs: Optional[set[int]] = None) ->
                             raise RuntimeError(f"Unsupported ref format: {new_parent_cref}")
                         parent_item.children.append(RefItem(cref=new_cref))
 
+            # rewrite FloatingItem explicit refs starting from start_indices to avoid corrupting items from prior calls
+            for key in post_processing_keys:
+                for idx_item in self.get_item_list(key)[start_indices[key] :]:
+                    if isinstance(idx_item, FloatingItem):
+                        idx_item.captions = [
+                            RefItem(cref=orig_ref_to_new_ref[cap.cref])
+                            for cap in idx_item.captions
+                            if cap.cref in orig_ref_to_new_ref
+                        ]
+                        idx_item.references = [
+                            RefItem(cref=orig_ref_to_new_ref[ref.cref])
+                            for ref in idx_item.references
+                            if ref.cref in orig_ref_to_new_ref
+                        ]
+                        idx_item.footnotes = [
+                            RefItem(cref=orig_ref_to_new_ref[fn.cref])
+                            for fn in idx_item.footnotes
+                            if fn.cref in orig_ref_to_new_ref
+                        ]
+
             # update pages
             new_max_page = None
             for page_nr in doc.pages:

test/data/doc/concatenated.html

@@ -109,6 +109,9 @@ <h2>1 Introduction</h2>
 <p>Copyright © 2025, Association for the Advancement of Artificial Intelligence (www.aaai.org). All rights reserved.</p>
 <p>The following list summarizes the features currently available on Docling:</p>
 <ul>
+<li style="list-style-type: '· ';">Parses common document formats (PDF, Images, MS Office formats, HTML) and exports to Markdown, JSON, and HTML.</li>
+<li style="list-style-type: '· ';">Applies advanced AI for document understanding, including detailed page layout, OCR, reading order, figure extraction, and table structure recognition.</li>
+<li style="list-style-type: '· ';">Establishes a unified DoclingDocument data model for rich document representation and operations.</li>
 <li style="list-style-type: '· ';">Provides fully local execution capabilities making it suitable for sensitive data and air-gapped environments.</li>
 <li style="list-style-type: '· ';">Has an ecosystem of plug-and-play integrations with prominent generative AI development frameworks, including LangChain and LlamaIndex.</li>
 <li style="list-style-type: '· ';">Can leverage hardware accelerators such as GPUs.</li>
@@ -343,12 +346,9 @@ <h2>1. Introduction</h2>
 </li>
 <li style="list-style-type: '■ ';">list item 4</li>
 </ul>
-<p>This is the caption of table 1.</p>
-<table><caption><div class="caption">Parses common document formats (PDF, Images, MS Office formats, HTML) and exports to Markdown, JSON, and HTML.</div></caption><tbody><tr><td rowspan="2">Product</td><td colspan="2">Years</td></tr><tr><td>2016</td><td>2017</td></tr><tr><td>Apple</td><td>49823</td><td>695944</td></tr></tbody></table>
-<p>This is the caption of figure 1.</p>
-<figure><figcaption><div class="caption">Applies advanced AI for document understanding, including detailed page layout, OCR, reading order, figure extraction, and table structure recognition.</div></figcaption></figure>
-<p>This is the caption of figure 2.</p>
-<figure><figcaption><div class="caption">Establishes a unified DoclingDocument data model for rich document representation and operations.</div></figcaption><img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAEAAAABACAIAAAAlC+aJAAAAIklEQVR4nO3BAQ0AAADCoPdPbQ8HFAAAAAAAAAAAAAAA8G4wQAABiwCo9wAAAABJRU5ErkJggg=="></figure>
+<table><caption><div class="caption">This is the caption of table 1.</div></caption><tbody><tr><td rowspan="2">Product</td><td colspan="2">Years</td></tr><tr><td>2016</td><td>2017</td></tr><tr><td>Apple</td><td>49823</td><td>695944</td></tr></tbody></table>
+<figure><figcaption><div class="caption">This is the caption of figure 1.</div></figcaption></figure>
+<figure><figcaption><div class="caption">This is the caption of figure 2.</div></figcaption><img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAEAAAABACAIAAAAlC+aJAAAAIklEQVR4nO3BAQ0AAADCoPdPbQ8HFAAAAAAAAAAAAAAA8G4wQAABiwCo9wAAAABJRU5ErkJggg=="></figure>
 <ul>
 <li style="list-style-type: '■ ';">item 1 of list</li>
 </ul>

test/data/doc/concatenated.json

@@ -12760,7 +12760,7 @@
       "prov": [],
       "captions": [
         {
-          "$ref": "#/texts/15"
+          "$ref": "#/texts/303"
         }
       ],
       "references": [],
@@ -12778,7 +12778,7 @@
       "prov": [],
       "captions": [
         {
-          "$ref": "#/texts/16"
+          "$ref": "#/texts/304"
         }
       ],
       "references": [],
@@ -13930,7 +13930,7 @@
       "prov": [],
       "captions": [
         {
-          "$ref": "#/texts/14"
+          "$ref": "#/texts/302"
         }
       ],
       "references": [],