feat: replace parent_id linked list with table_id/chunk_index/total_chunks

Replace the parent_id linked list approach for table reconstruction with
explicit chunk sequencing metadata per ML-1020:
- table_id: shared UUID for all chunks from the same table
- chunk_index: 0-based position in the chunk sequence
- total_chunks: total number of chunks for the table

Update reconstruct_table_from_chunks to group by table_id and order by
chunk_index instead of walking parent_id chains.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: qued

unstructured/chunking/base.py

@@ -4,6 +4,7 @@
 
 import collections
 import copy
+import uuid
 from typing import Any, Callable, DefaultDict, Iterable, Iterator, cast
 
 import regex
@@ -927,26 +928,27 @@ def _make_table_chunks(
     ) -> Iterator[TableChunk]:
         """Form `TableChunk` objects from (text, html) pairs.
 
-        Handles `is_continuation` and `parent_id` linking so each chunk points to the previous
-        one, allowing reconstruction of the original table.
+        Handles `is_continuation` and chunk sequencing metadata (`table_id`, `chunk_index`,
+        `total_chunks`) so the original table can be reconstructed from its chunks.
         """
-        is_continuation = False
-        prev_id = None
+        # -- collect all pairs first so we know total_chunks --
+        pairs = list(text_html_pairs)
+        table_id = str(uuid.uuid4())
+        total_chunks = len(pairs)
 
-        for text, html in text_html_pairs:
+        for chunk_index, (text, html) in enumerate(pairs):
             metadata = self._metadata
             if html is not None:
                 metadata.text_as_html = html
             else:
                 metadata.text_as_html = None
             # -- second and later chunks get `.metadata.is_continuation = True` --
-            metadata.is_continuation = is_continuation or None
-            is_continuation = True
+            metadata.is_continuation = (chunk_index > 0) or None
 
             chunk = TableChunk(text=text, metadata=metadata)
-            if prev_id is not None:
-                chunk.metadata.parent_id = prev_id
-            prev_id = chunk.id
+            chunk.metadata.table_id = table_id
+            chunk.metadata.chunk_index = chunk_index
+            chunk.metadata.total_chunks = total_chunks
             yield chunk
 
     @property

unstructured/chunking/dispatch.py

@@ -135,39 +135,30 @@ def kw_arg_names(self) -> tuple[str, ...]:
 def reconstruct_table_from_chunks(elements: Iterable[Element]) -> list[Table]:
     """Reconstruct original tables from a mixed list of chunked elements.
 
-    Filters `TableChunk` elements, groups them by their `parent_id` linked lists, and merges
-    each group into a single `Table` with combined text and HTML. Non-`TableChunk` elements
-    are ignored. Returns reconstructed tables in reading order (order of first chunk appearance).
+    Filters `TableChunk` elements, groups them by `table_id`, orders by `chunk_index`, and
+    merges each group into a single `Table` with combined text and HTML. Non-`TableChunk`
+    elements are ignored. Returns reconstructed tables in reading order (order of first chunk
+    appearance).
     """
     # -- filter to only TableChunk instances, preserving input order --
     table_chunks = [e for e in elements if isinstance(e, TableChunk)]
     if not table_chunks:
         return []
 
-    # -- index chunks by id so we can follow parent_id links --
-    chunk_by_id: dict[str, TableChunk] = {c.id: c for c in table_chunks}
-
-    # -- identify head chunks: parent_id is None or points outside this set --
-    heads = [
-        c
-        for c in table_chunks
-        if c.metadata.parent_id is None or c.metadata.parent_id not in chunk_by_id
-    ]
-
-    # -- build a child lookup: parent_id -> chunk --
-    child_of: dict[str, TableChunk] = {
-        c.metadata.parent_id: c for c in table_chunks if c.metadata.parent_id is not None
-    }
-
-    # -- for each head, walk the chain and merge into a Table --
+    # -- group by table_id, preserving first-seen order --
+    groups: dict[str, list[TableChunk]] = {}
+    for chunk in table_chunks:
+        tid = chunk.metadata.table_id
+        if tid is None:
+            continue
+        if tid not in groups:
+            groups[tid] = []
+        groups[tid].append(chunk)
+
+    # -- sort each group by chunk_index and merge --
     tables: list[Table] = []
-    for head in heads:
-        group = [head]
-        current = head
-        while current.id in child_of:
-            current = child_of[current.id]
-            group.append(current)
-
+    for group in groups.values():
+        group.sort(key=lambda c: c.metadata.chunk_index or 0)
         tables.append(_merge_table_chunks(group))
 
     return tables
@@ -181,7 +172,9 @@ def _merge_table_chunks(chunks: list[TableChunk]) -> Table:
     # -- build metadata from first chunk --
     metadata = copy.deepcopy(chunks[0].metadata)
     metadata.is_continuation = None
-    metadata.parent_id = None
+    metadata.table_id = None
+    metadata.chunk_index = None
+    metadata.total_chunks = None
 
     # -- combine HTML if all chunks have it --
     if all(c.metadata.text_as_html for c in chunks):

unstructured/documents/elements.py

@@ -212,6 +212,11 @@ class ElementMetadata:
     text_as_html: Optional[str]
     is_extracted: Optional[str]
     table_as_cells: Optional[dict[str, str | int]]
+
+    # -- used for TableChunk elements to enable table reconstruction --
+    table_id: Optional[str]
+    chunk_index: Optional[int]
+    total_chunks: Optional[int]
     url: Optional[str]
 
     # -- speech-to-text segment timestamps (seconds) when element is from partition_audio --
@@ -261,6 +266,9 @@ def __init__(
         signature: Optional[str] = None,
         subject: Optional[str] = None,
         table_as_cells: Optional[dict[str, str | int]] = None,
+        table_id: Optional[str] = None,
+        chunk_index: Optional[int] = None,
+        total_chunks: Optional[int] = None,
         text_as_html: Optional[str] = None,
         url: Optional[str] = None,
         segment_end_seconds: Optional[float] = None,
@@ -311,6 +319,9 @@ def __init__(
         self.subject = subject
         self.text_as_html = text_as_html
         self.table_as_cells = table_as_cells
+        self.table_id = table_id
+        self.chunk_index = chunk_index
+        self.total_chunks = total_chunks
         self.url = url
         self.segment_end_seconds = segment_end_seconds
         self.segment_start_seconds = segment_start_seconds
@@ -536,6 +547,9 @@ def field_consolidation_strategies(cls) -> dict[str, ConsolidationStrategy]:
             "subject": cls.FIRST,
             "text_as_html": cls.STRING_CONCATENATE,
             "table_as_cells": cls.FIRST,  # -- only occurs in Table --
+            "table_id": cls.DROP,  # -- added by chunking, not before --
+            "chunk_index": cls.DROP,  # -- added by chunking, not before --
+            "total_chunks": cls.DROP,  # -- added by chunking, not before --
             "url": cls.FIRST,
             # TODO: ideally a chunk spanning multiple audio segments would keep min(start) and
             # max(end) across its constituent elements. ConsolidationStrategy currently has no