feat: Add readingorder model

[PeterStaar-IBM]

Checklist:

• Commit Message Formatting: Commit titles and messages follow guidelines in the
  conventional commits.
• Documentation has been updated, if necessary.
• Examples have been added, if necessary.
• Tests have been added, if necessary.

[mllife]

Are you rewriting the C++ code from ds_glm_model for ordering as references here; DS4SD/docling#361 (reply in thread)

[mergify]

Merge Protections

Your pull request matches the following merge protections and will not be merged until they are valid.

🟢 Enforce conventional commit

Wonderful, this rule succeeded.

Make sure that we follow https://www.conventionalcommits.org/en/v1.0.0/

• title ~= ^(fix|feat|docs|style|refactor|perf|test|build|ci|chore|revert)(?:\(.+\))?(!)?:

🟢 Require two reviewer for test updates

Wonderful, this rule succeeded.

When test data is updated, we require two reviewers

• #approved-reviews-by >= 2

[cau-git]

As far as I can see, the output of the predict_reading_order is a permutation of the page_elements it accepts as an input. This argument is a list of objects following a custom PageElement data model, combined from BoundingBox and DocItem attributes.
To make sure there is a consistent interface for DoclingDocument, the test unit should demonstrate how one needs to apply this resorted page_elements list to the DoclingDocument for all the supported operations:

• Change the order of DocItem instances in the body of a DoclingDocument
• Change multiple separate DocItem instances to a single DocItem instance when they must be merged (i.e. two or more provenances in one item)
• Change a DocItem to have a caption or footnote etc. referencing to it.

(All of this obviously also needs API extensions on DoclingDocument)

Ultimately, the higher-level reading-order model must have an API that accepts a DoclingDocument and returns a new DoclingDocument with correct order. That does not necessarily need to happen in docling-ibm-models but it should be as easy as possible outside in case.

[dolfim-ibm]

Ultimately, the higher-level reading-order model must have an API that accepts a DoclingDocument and returns a new DoclingDocument with correct order

High-level I agree with the statement, but how do we see happening the merging of items? E.g. the paragraphs split among columns or pages? They are very likely identified only after the pieces are in the correct reading-order, which means the DoclingDocument items are not yet completely defined.

[PeterStaar-IBM]

@cau-git I dont think you fully grasp how we design the reading-order model. It seperates out in different tasks, in order to not get confused.

1. It orders a set of PageElements. This ensures that we always return exactly the same number of elements as we get.
2. It generates links between PageElements (to_caption, to_footnote, merge) in order to collapse PageElements into DocItems

We could have a higher level method that takes a DoclingDocument and returns an ordered one, but we also need the low-level, so we can measure the accuracy of the methods.

[cau-git]

I clearly understand why we need the low level methods. What I want to understand is if we want to start from a DoclingDocument representation (like this test assumes) or from an internal representation like what the layout model produces. The current state would allow for both.

[dolfim-ibm]

lgtm 🚀