docling-project / docling-project/docling

Allow custom chunking options in the service clients

Open
#3,982 0 comments 0 reactions 0 assignees View on GitHub
enhancement
Dominant language
Python
Stars
66.4k
Forks
4.8k
Avg merge
2d 21h
Merged PRs (30d)
84

Description

### Requested feature
I would like the sync and async Docling service clients to accept custom chunking options.

Docling Serve already supports options such as `use_markdown_tables`. When this option is enabled, tables inside chunks are written as Markdown tables instead of row triplets.

This is useful for applications that use the service client for remote chunking. For example, an application may want tables inside chunks to be serialized as Markdown tables. Today, the service client always creates default `HybridChunkerOptions` or `HierarchicalChunkerOptions` internally, so callers cannot enable `use_markdown_tables`.

I suggest adding an optional keyword argument named `chunking_options`:

```python
from docling.datamodel.service.chunking import HybridChunkerOptions
from docling.service_client import ChunkerKind

job = await client.submit_chunk(
source=document,
chunker=ChunkerKind.HYBRID,
chunking_options=HybridChunkerOptions(
max_tokens=512,
use_markdown_tables=True,
),
)
```

This should be supported by:

- DoclingServiceClient.chunk()
- DoclingServiceClient.submit_chunk()
- AsyncDoclingServiceClient.submit_chunk()

It should work for both uploaded files and URL sources.

If chunking_options is not provided, the current default behavior should stay the same. If the selected chunker and the type of chunking_options do not match, the client could raise a clear error.

The main design question is whether the client should keep the existing chunker argument and add chunking_options, or infer the chunker from the options object. Keeping chunker would be backward
compatible, so that is my preferred option.

I can submit a PR with this change and tests if this design is accepted.

### Alternatives
Applications can call the Docling Serve HTTP endpoints directly and send `chunking_use_markdown_tables=true`. However, this means duplicating upload, authentication, polling, and error-handling code that already exists in the service client.

Another option is to pass chunking settings through `ConvertDocumentsOptions`. This is unclear because conversion options and chunking options are separate parts of the Docling Serve chunking request. The service client also creates its own default chunking options, so values inside `ConvertDocumentsOptions` are not used as the request’s chunking options.

Contributor guide

Open the contributing guide

Research direction

Start with DoclingServiceClient.chunk(), DoclingServiceClient.submit_chunk(), and AsyncDoclingServiceClient.submit_chunk(), tracing how they create default HybridChunkerOptions or HierarchicalChunkerOptions for uploaded files and URL sources. Preserve current defaults when chunking_options is omitted, pass supplied options through, and verify mismatched chunker types produce a clear error if that design is retained. Done means both sync and async clients support custom options such as use_markdown_tables.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
api
Issue type
Feature
Difficulty
3/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
68/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.