docling-project / docling-project/docling-serve
Include provenance (bbox + page_no) inline in chunk endpoint response
- Dominant language
- Python
- Stars
- 1.8k
- Forks
- 340
- Avg merge
- 6d 11h
- Merged PRs (30d)
- 8
Description
The /v1/chunk/hybrid/file and /v1/chunk/hybrid/source endpoints currently return doc_items as JSON Pointer references (e.g. "#/texts/0") without resolving the underlying provenance data. As a result, bounding box and page number information is not available in the chunk response.
Page numbers are surfaced separately as a flat page_numbers array, but bounding boxes are completely absent. The only workaround is to make a second call to the convert endpoint with to_formats: ["json"] and resolve the refs client-side — meaning the document goes through the full AI processing pipeline twice, which doubles latency.
This is particularly painful because docling's conversion is the slow part. The chunking itself is fast. The server already has the fully resolved DoclingDocument in memory when it builds the chunk response — it just doesn't include the prov data in the output.
**Requested change**
When serializing doc_items in the chunk response, include the resolved prov array for each item inline, rather than returning bare refs. Concretely, instead of:
`"doc_items": ["#/texts/0"] `
return:
```
"doc_items": [
{
"self_ref": "#/texts/0",
"label": "text",
"prov": [
{
"page_no": 1,
"bbox": { "l": 108.0, "t": 405.1, "r": 504.0, "b": 330.7, "coord_origin": "BOTTOMLEFT" },
"charspan": [0, 608]
}
]
}
]
```
Alternatively, a flag like chunking_include_provenance: true would be acceptable if there's concern about response size, though given that chunks already carry text content, the bbox data is small by comparison.
**Use case**
RAG pipelines that need to highlight or cite source regions in the original document (e.g. rendering a bounding box overlay on the PDF page) currently cannot do so without a double-pass. This is a common requirement for document grounding in RAG applications.
Thank you for considering, this extension would be really heplfull.
Contributor guide
Research direction
Start by tracing serialization for the /v1/chunk/hybrid/file and /v1/chunk/hybrid/source endpoints, then inspect how their resolved DoclingDocument produces doc_items. The work is done when each returned item includes its self_ref, label, and resolved prov data with page_no, bbox, and charspan, without requiring a second convert request.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- api, backend
- Issue type
- Feature
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 55/100