docling-serve-client 0.0.0-stage → 0.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +201 -0
- package/README.md +527 -2
- package/dist/capabilities.d.ts +10 -0
- package/dist/capabilities.d.ts.map +1 -0
- package/dist/client.d.ts +11 -0
- package/dist/client.d.ts.map +1 -0
- package/dist/core/http.d.ts +12 -0
- package/dist/core/http.d.ts.map +1 -0
- package/dist/core/input.d.ts +18 -0
- package/dist/core/input.d.ts.map +1 -0
- package/dist/core/pdf.d.ts +11 -0
- package/dist/core/pdf.d.ts.map +1 -0
- package/dist/core/result.d.ts +54 -0
- package/dist/core/result.d.ts.map +1 -0
- package/dist/core/validate.d.ts +29 -0
- package/dist/core/validate.d.ts.map +1 -0
- package/dist/document.d.ts +412 -0
- package/dist/document.d.ts.map +1 -0
- package/dist/images.d.ts +70 -0
- package/dist/images.d.ts.map +1 -0
- package/dist/index.d.ts +6 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +968 -0
- package/dist/index.js.map +19 -0
- package/dist/options.d.ts +64 -0
- package/dist/options.d.ts.map +1 -0
- package/dist/response.d.ts +27 -0
- package/dist/response.d.ts.map +1 -0
- package/dist/types.d.ts +459 -0
- package/dist/types.d.ts.map +1 -0
- package/package.json +74 -4
- package/src/capabilities.ts +109 -0
- package/src/client.ts +480 -0
- package/src/core/http.ts +96 -0
- package/src/core/input.ts +75 -0
- package/src/core/pdf.ts +54 -0
- package/src/core/result.ts +54 -0
- package/src/core/validate.ts +85 -0
- package/src/document.ts +417 -0
- package/src/images.ts +337 -0
- package/src/index.ts +69 -0
- package/src/options.ts +350 -0
- package/src/response.ts +218 -0
- package/src/types.ts +513 -0
package/README.md
CHANGED
|
@@ -1,3 +1,528 @@
|
|
|
1
|
-
|
|
1
|
+
[](https://github.com/martin-winkler-dev/docling-serve-client-js/actions/workflows/test.yml)
|
|
2
|
+
[](https://github.com/martin-winkler-dev/docling-serve-client-js/actions/workflows/package.yml)
|
|
3
|
+
[](https://bun.sh)
|
|
4
|
+
[](https://nodejs.org)
|
|
5
|
+
[](LICENSE)
|
|
2
6
|
|
|
3
|
-
|
|
7
|
+
# docling-serve-client
|
|
8
|
+
|
|
9
|
+
Typed HTTP client for a running [docling-serve](https://github.com/docling-project/docling-serve): **PDF or image
|
|
10
|
+
bytes in, docling's Markdown or DoclingDocument JSON out**.
|
|
11
|
+
|
|
12
|
+
- Two outputs: `convertMarkdown` returns docling's Markdown unchanged except for image handling; `convertDocument`
|
|
13
|
+
returns the DoclingDocument (the JSON AST with labels, reading order, pages and bounding boxes) as docling sends it.
|
|
14
|
+
- No cleanup, no heuristics on text. Repairs and analysis belong in the code that uses this client. The Markdown is
|
|
15
|
+
docling's raw output, e.g. with `&` entities, soft hyphens and dot leaders left in.
|
|
16
|
+
- In-memory only: no file I/O, no streaming.
|
|
17
|
+
- **Calls never throw on runtime failures.** Every call resolves to `{ ok: true, data } | { ok: false, error }`.
|
|
18
|
+
Two exceptions are programming errors: the factory throws a `TypeError` on invalid config, and any call with an
|
|
19
|
+
invalid option rejects with a `TypeError` before sending a request.
|
|
20
|
+
- Sync (`convert*`) and async (`submit*` + `check`). No built-in polling, queueing or rate limiting.
|
|
21
|
+
- Zero dependencies. ESM, works in Node ≥ 22.12 (also via `require()`) and Bun.
|
|
22
|
+
|
|
23
|
+
## Installation
|
|
24
|
+
|
|
25
|
+
```bash
|
|
26
|
+
bun add docling-serve-client
|
|
27
|
+
# or
|
|
28
|
+
npm install docling-serve-client
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
## Usage
|
|
32
|
+
|
|
33
|
+
```ts
|
|
34
|
+
import { readFile } from 'node:fs/promises';
|
|
35
|
+
import { createDoclingClient } from 'docling-serve-client';
|
|
36
|
+
|
|
37
|
+
const docling = createDoclingClient({ baseUrl: 'http://127.0.0.1:5001' });
|
|
38
|
+
|
|
39
|
+
// Input is always a Uint8Array (Node Buffer is one): a PDF, or a PNG, JPEG, TIFF or WebP image
|
|
40
|
+
const pdf = await readFile('paper.pdf');
|
|
41
|
+
// const pdf = await Bun.file('paper.pdf').bytes(); // Bun
|
|
42
|
+
// const pdf = new Uint8Array(await (await fetch(pdfUrl)).arrayBuffer()); // any download
|
|
43
|
+
|
|
44
|
+
const md = await docling.convertMarkdown(pdf);
|
|
45
|
+
if (md.ok) console.log(md.data.markdown, md.data.warnings);
|
|
46
|
+
|
|
47
|
+
const doc = await docling.convertDocument(pdf);
|
|
48
|
+
if (doc.ok) {
|
|
49
|
+
for (const item of doc.data.document.texts) {
|
|
50
|
+
if (item.label === 'section_header') console.log(item.level, item.text, item.prov[0]?.page_no);
|
|
51
|
+
}
|
|
52
|
+
} else {
|
|
53
|
+
console.error(doc.error.code, doc.error.message);
|
|
54
|
+
}
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
### Async
|
|
58
|
+
|
|
59
|
+
`submitMarkdown()` and `submitDocument()` return a plain JSON job object. Store all of it and pass it back to
|
|
60
|
+
`check()`. A Markdown job carries its image handling, so `check()` works the same from another process or after a
|
|
61
|
+
restart. `check()` returns the result type that matches the job's `kind`. The job also carries the
|
|
62
|
+
[conversion settings](#conversion-settings) of its submission; `check()` does not need them, so a stored job may omit
|
|
63
|
+
`settings`, and the `done` state does not repeat them.
|
|
64
|
+
|
|
65
|
+
```ts
|
|
66
|
+
import type { DocumentJob } from 'docling-serve-client';
|
|
67
|
+
|
|
68
|
+
const job = await docling.submitDocument(pdf);
|
|
69
|
+
if (!job.ok) return handle(job.error);
|
|
70
|
+
await save(JSON.stringify(job.data)); // { kind: 'document', id, settings }
|
|
71
|
+
|
|
72
|
+
// later, as often as you like (e.g. in a polling loop or another worker):
|
|
73
|
+
const storedJob: DocumentJob = JSON.parse(await load());
|
|
74
|
+
const state = await docling.check(storedJob);
|
|
75
|
+
if (state.ok) {
|
|
76
|
+
switch (state.data.status) {
|
|
77
|
+
case 'queued': console.log('Queue position:', state.data.position); break;
|
|
78
|
+
case 'running': console.log('Processing...'); break;
|
|
79
|
+
case 'done': use(state.data.document); break;
|
|
80
|
+
}
|
|
81
|
+
} else {
|
|
82
|
+
// state.error.code: 'not_found' (e.g. expired or unknown id), 'http', 'conversion_failed', etc.
|
|
83
|
+
console.error(state.error.code, state.error.message);
|
|
84
|
+
}
|
|
85
|
+
|
|
86
|
+
// In-process polling loop until done:
|
|
87
|
+
while (true) {
|
|
88
|
+
const poll = await docling.check(storedJob);
|
|
89
|
+
if (!poll.ok) {
|
|
90
|
+
console.error('Job error:', poll.error.code, poll.error.message);
|
|
91
|
+
break;
|
|
92
|
+
}
|
|
93
|
+
if (poll.data.status === 'done') {
|
|
94
|
+
use(poll.data.document);
|
|
95
|
+
break;
|
|
96
|
+
}
|
|
97
|
+
await new Promise((resolve) => setTimeout(resolve, 1000));
|
|
98
|
+
}
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
For Markdown jobs (`submitMarkdown`), `check()` returns `JobState<ConvertedMarkdown>` whose `done` state provides
|
|
102
|
+
`markdown`, `images`, `warnings`, and `versions`.
|
|
103
|
+
|
|
104
|
+
docling-serve deletes a result `DOCLING_SERVE_RESULT_REMOVAL_DELAY` seconds (default 300) after its first fetch
|
|
105
|
+
(`DOCLING_SERVE_SINGLE_USE_RESULTS=true`, the default). A `check()` whose result download failed (network error,
|
|
106
|
+
`timeoutMs`, abort) can be repeated within that time; later `check()` returns `not_found` (`Result already fetched or
|
|
107
|
+
expired`), so persist the `done` data. Start docling-serve with `DOCLING_SERVE_SINGLE_USE_RESULTS=false` to keep results
|
|
108
|
+
until they expire. These are server settings; `convert*()` is not affected.
|
|
109
|
+
|
|
110
|
+
### Options
|
|
111
|
+
|
|
112
|
+
Set docling options on the factory and override them per call, key by key; `ocrLang`, `pageRange` and
|
|
113
|
+
`documentTimeout` are factory-only and reject per call. Nothing is silently ignored or converted:
|
|
114
|
+
an unknown option or an invalid value throws a `TypeError` at the start of the call, before any request
|
|
115
|
+
(`Option "x" is not supported`, `Invalid value for option "x"`; nested keys are named like `imageOptions.prefix`).
|
|
116
|
+
|
|
117
|
+
```ts
|
|
118
|
+
const docling = createDoclingClient({
|
|
119
|
+
baseUrl: 'http://127.0.0.1:5001',
|
|
120
|
+
apiKey: '…', // only if docling-serve requires X-Api-Key
|
|
121
|
+
timeoutMs: 120_000, // optional limit per request; on expiry the call resolves with `aborted`
|
|
122
|
+
options: { ocrLang: ['de', 'en'] }, // docling defaults for every call
|
|
123
|
+
fetch: myFetch, // optional custom fetch
|
|
124
|
+
});
|
|
125
|
+
|
|
126
|
+
await docling.convertDocument(pdf, { ocr: false, images: 'placeholder', signal: AbortSignal.timeout(60_000) });
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
docling options (factory and per call):
|
|
130
|
+
|
|
131
|
+
| option | default | effect |
|
|
132
|
+
|---|---|---|
|
|
133
|
+
| `headingHierarchy` | `true` | heading levels by bookmarks, numbering and font; `false` = every heading level 1 |
|
|
134
|
+
| `formulaEnrichment` | `true` | formulas as LaTeX (extra model; runs only on formulas); without it formula `text` is empty and the md shows `<!-- formula-not-decoded -->` |
|
|
135
|
+
| `codeEnrichment` | `false` | code listings via extra model (slower) |
|
|
136
|
+
| `chartExtraction` | `false` | charts as data (vision model, slower) |
|
|
137
|
+
| `pipeline` | `'standard'` | `'vlm'` runs a vision-language model per page (slow) |
|
|
138
|
+
| `pdfBackend` | `'docling_parse'` | text extractor; `'pypdfium2'` reads ligatures and word spaces better but misses page headers and footers |
|
|
139
|
+
| `ocr` | `true` | OCR bitmap content of PDFs (scans, pictures); image input is always OCRed |
|
|
140
|
+
| `forceOcr` | `false` | OCR whole PDF pages and drop their text layer, for PDFs with broken text; ignored for image input |
|
|
141
|
+
| `ocrEngine` | `'auto'` | OCR engine preset (`ocr_preset`): `'auto'`, `'rapidocr'`, `'easyocr'`, `'tesseract'`, `'tesserocr'`, `'ocrmac'` or any other non-empty preset id; the server rejects an id it does not allow with `http` 422, see [server capabilities](#server-capabilities) |
|
|
142
|
+
|
|
143
|
+
Factory only (`options` of `createDoclingClient`; per call they reject with `Option "x" is not supported`). Use a second
|
|
144
|
+
client for other values:
|
|
145
|
+
|
|
146
|
+
| option | default | effect |
|
|
147
|
+
|---|---|---|
|
|
148
|
+
| `ocrLang` | engine default | BCP-47 hints in order of preference, e.g. `['de', 'en-US']`; `[]` = engine default |
|
|
149
|
+
| `pageRange` | all pages | `[from, to]`, 1-based, inclusive |
|
|
150
|
+
| `documentTimeout` | server default | server-side limit in seconds |
|
|
151
|
+
|
|
152
|
+
Per call only (not allowed in factory `options`, rejected with `Option "x" is not supported`):
|
|
153
|
+
|
|
154
|
+
| option | calls | default | effect |
|
|
155
|
+
|---|---|---|---|
|
|
156
|
+
| `images` | `convertMarkdown`, `submitMarkdown` | `'placeholder'` | `'placeholder'`, `'none'`, or `'extract'` |
|
|
157
|
+
| `imageOptions` | `convertMarkdown`, `submitMarkdown` | none | `{ prefix: string, omitSmall?: boolean }`; required with `images: 'extract'`, not allowed otherwise |
|
|
158
|
+
| `images` | `convertDocument`, `submitDocument` | `'embedded'` | `'embedded'` or `'placeholder'` |
|
|
159
|
+
| `pageImages` | `convertDocument`, `submitDocument` | `false` | renders pages as images, decoded in `pageImages` |
|
|
160
|
+
| `signal` | all calls (`convert*`, `submit*`, `check`, `capabilities`) | none | `AbortSignal` to cancel the request |
|
|
161
|
+
|
|
162
|
+
`timeoutMs` is a factory setting: it limits every request except `GET /version` and is combined with `signal`.
|
|
163
|
+
|
|
164
|
+
Always on, not configurable: table structure with the accurate TableFormer model (`do_table_structure`,
|
|
165
|
+
`table_mode: 'accurate'`, `table_structure_preset: 'tableformer_v1_accurate'`, `table_cell_matching`), pictures and
|
|
166
|
+
page images at 144 dpi (`images_scale=2`, exported as `PAGE_IMAGE_SCALE`) and, for Markdown, compact tables
|
|
167
|
+
(`md_compact_tables`) without page break placeholders (`md_page_break_placeholder`). The image scale does not affect
|
|
168
|
+
OCR: docling OCRs at its own fixed 216 dpi. Model presets are pinned: `granite_docling` for `pipeline: 'vlm'`,
|
|
169
|
+
`granite_vision_v4` for `chartExtraction`, `codeformulav2` for formula and code enrichment. Picture classification
|
|
170
|
+
and description stay off.
|
|
171
|
+
|
|
172
|
+
### Input formats
|
|
173
|
+
|
|
174
|
+
The format is detected from the first bytes; anything else resolves to `invalid_input` without a request.
|
|
175
|
+
|
|
176
|
+
| input | detected by | sent as |
|
|
177
|
+
|---|---|---|
|
|
178
|
+
| PDF | `%PDF-` within the first 1024 bytes | `from_formats=pdf`, `document.pdf` |
|
|
179
|
+
| PNG, JPEG, TIFF, WebP | file signature at byte 0 | `from_formats=image`, `document.png` / `.jpg` / `.tiff` / `.webp` |
|
|
180
|
+
|
|
181
|
+
An image is converted as one page: docling runs layout detection and OCR on it, and `ocrLang` applies. OCR is always
|
|
182
|
+
on for images and never full-page: `ocr: false` would return no text, and `forceOcr: true` merges words (`stepsand`),
|
|
183
|
+
so both are ignored for image input. Use it e.g. to re-read a crop of a page whose text layer is broken. Text only
|
|
184
|
+
comes back if the server has a working OCR engine. PDF-only options (`pdfBackend`, `pageRange`) have no effect on
|
|
185
|
+
images.
|
|
186
|
+
|
|
187
|
+
### Images in the DoclingDocument
|
|
188
|
+
|
|
189
|
+
| `images` | effect |
|
|
190
|
+
|---|---|
|
|
191
|
+
| `'embedded'` (default) | `pictures[].image.uri` is a `data:image/png;base64,…` URI; pictures keep their position, captions and size |
|
|
192
|
+
| `'placeholder'` | `pictures[].image` is `null`; the picture items stay, the document is much smaller |
|
|
193
|
+
|
|
194
|
+
The base64 data stays inside the document. Pull it out when you need files, e.g. when rendering Markdown from the
|
|
195
|
+
document. `isSmallImage(picture.image.size)` applies the same size filter as `omitSmall` (see below).
|
|
196
|
+
|
|
197
|
+
### Page images
|
|
198
|
+
|
|
199
|
+
`pageImages: true` (documents only, default `false`) asks docling to render every page (`include_page_images`). The
|
|
200
|
+
client moves them out of the document: `document.pages[n].image` is always `null`, so the JSON stays small, and the
|
|
201
|
+
images come back decoded in `data.pageImages`, in page order:
|
|
202
|
+
|
|
203
|
+
```ts
|
|
204
|
+
import { writeFile } from 'node:fs/promises';
|
|
205
|
+
|
|
206
|
+
const res = await docling.convertDocument(pdf, { pageImages: true, images: 'placeholder' });
|
|
207
|
+
if (res.ok) {
|
|
208
|
+
await writeFile(`out/${docId}.json`, JSON.stringify(res.data.document)); // no page image data inside
|
|
209
|
+
for (const image of res.data.pageImages) {
|
|
210
|
+
await writeFile(`out/${docId}-p${image.page}.png`, image.bytes); // { page, mimeType, width, height, dpi, bytes }
|
|
211
|
+
}
|
|
212
|
+
}
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
- `page` is the 1-based PDF page (absolute, also with `pageRange`); `dpi` is always 144.
|
|
216
|
+
- `width` and `height` are pixels from the PNG header, else docling's `image.size`. Pixel size = page size in points
|
|
217
|
+
× 2; an A4 page is about 1190 × 1684 px and 0.4 to 0.6 MB as PNG.
|
|
218
|
+
- Page images are independent of `images`: `images: 'placeholder'` drops picture data and keeps page images.
|
|
219
|
+
- Async: `submitDocument(pdf, { pageImages: true })` stores nothing extra in the job; `check()` returns the images.
|
|
220
|
+
- A page image that is not a base64 data URI or has invalid or empty data is missing from `pageImages`, stays in
|
|
221
|
+
`document.pages[].image` as docling sent it, and is reported as a `page_image_not_decoded` warning (`details.page`).
|
|
222
|
+
|
|
223
|
+
The document keeps docling's bboxes as sent: PDF points, mostly with a bottom-left origin. `toPageImageBox` maps one
|
|
224
|
+
onto its page image as `{ page, x, y, width, height }` in pixels with a top-left origin (unrounded), ready to store
|
|
225
|
+
next to the page image file or to crop with:
|
|
226
|
+
|
|
227
|
+
```ts
|
|
228
|
+
import { toPageImageBox } from 'docling-serve-client';
|
|
229
|
+
|
|
230
|
+
for (const item of res.data.document.texts) {
|
|
231
|
+
for (const prov of item.prov) {
|
|
232
|
+
const box = toPageImageBox(res.data.document, prov); // undefined if coordinates or page missing
|
|
233
|
+
}
|
|
234
|
+
}
|
|
235
|
+
|
|
236
|
+
// table cells carry their own bbox (top-left origin) and belong to the page of their table:
|
|
237
|
+
for (const table of res.data.document.tables) {
|
|
238
|
+
const pageNo = table.prov[0]?.page_no ?? 1;
|
|
239
|
+
for (const row of table.data.grid) {
|
|
240
|
+
for (const cell of row) {
|
|
241
|
+
if (cell.bbox) {
|
|
242
|
+
const box = toPageImageBox(res.data.document, { page_no: pageNo, bbox: cell.bbox });
|
|
243
|
+
}
|
|
244
|
+
}
|
|
245
|
+
}
|
|
246
|
+
}
|
|
247
|
+
```
|
|
248
|
+
|
|
249
|
+
The boxes fit page images of any conversion by this client, also when `pageImages` was off.
|
|
250
|
+
|
|
251
|
+
### DoclingDocument structure
|
|
252
|
+
|
|
253
|
+
`convertDocument()` returns the full JSON AST (`doc.data.document`) typed as `DoclingDocument`:
|
|
254
|
+
|
|
255
|
+
- `texts`: array of text blocks (`label`, `text`, `orig`, `prov: [{ page_no, bbox, charspan }]`). Common labels include `'paragraph'`, `'section_header'`, `'title'`, `'list_item'`, `'code'`, `'formula'`, `'footnote'`, `'page_header'`, `'page_footer'`, `'caption'`. Section headers include heading `level`. List items include `enumerated` and `marker`. Code listings include `code_language`. Formulas contain LaTeX in `text` with `formulaEnrichment`. Note on `prov.charspan`: `[start, end)` span is in Python Unicode code points; slice in JS using `Array.from(item.text).slice(start, end).join('')`, not `item.text.slice(start, end)`.
|
|
256
|
+
- `tables`: array of tables (`prov`, `data: { grid: TableCell[][], num_rows, num_cols }`). Cells contain `text`, `row_span`, `col_span`, `bbox`, `column_header`, and `row_header`.
|
|
257
|
+
- `pictures`: array of figures with `captions`, `prov`, `image` (`ImageRef` with base64 data URI when `images: 'embedded'`, or `null` when `images: 'placeholder'`), and `annotations` (e.g. chart data when `chartExtraction` was enabled, classifications, descriptions).
|
|
258
|
+
- `groups`: structural groupings (`(ListGroup | InlineGroup | GroupItem)[]`) such as lists, inline formatting runs, chapters, or form sections.
|
|
259
|
+
- `key_value_items`: key-value regions extracted from forms or documents (`graph: { cells: GraphCell[], links: GraphLink[] }`).
|
|
260
|
+
- `form_items`: form regions and form fields (`graph: { cells: GraphCell[], links: GraphLink[] }`).
|
|
261
|
+
- `pages`: record of page metadata keyed by 1-based page number string (`"1"`, `"2"`, ...) with `size: { width, height }` in PDF points.
|
|
262
|
+
- `body`: root group of content in reading order. Walk `body.children` (`{ $ref: string }` JSON pointers, e.g. `'#/texts/0'`) depth-first to follow the logical document flow.
|
|
263
|
+
- `furniture`: root group of header, footer and page number items outside the body flow.
|
|
264
|
+
|
|
265
|
+
#### Navigating the AST in reading order
|
|
266
|
+
|
|
267
|
+
The root content in reading order is stored in `body.children`. Each child is a JSON pointer reference (e.g. `#/texts/0`, `#/tables/1`, `#/groups/2`). You can resolve references and walk the reading order like this:
|
|
268
|
+
|
|
269
|
+
```ts
|
|
270
|
+
import type { DoclingDocument } from 'docling-serve-client';
|
|
271
|
+
|
|
272
|
+
// Resolving a JSON pointer reference (e.g. '#/texts/0'):
|
|
273
|
+
function resolveRef(doc: DoclingDocument, ref: string) {
|
|
274
|
+
const [, collection, idx] = ref.split('/');
|
|
275
|
+
return (doc as Record<string, any>)[collection]?.[Number(idx)];
|
|
276
|
+
}
|
|
277
|
+
|
|
278
|
+
// Walking body items in logical reading order:
|
|
279
|
+
function* walkReadingOrder(
|
|
280
|
+
doc: DoclingDocument,
|
|
281
|
+
node: { children: { $ref: string }[] } = doc.body,
|
|
282
|
+
): Generator<any> {
|
|
283
|
+
for (const child of node.children) {
|
|
284
|
+
const item = resolveRef(doc, child.$ref);
|
|
285
|
+
if (!item) continue;
|
|
286
|
+
if ('children' in item && Array.isArray(item.children) && item.children.length > 0) {
|
|
287
|
+
yield* walkReadingOrder(doc, item);
|
|
288
|
+
} else {
|
|
289
|
+
yield item;
|
|
290
|
+
}
|
|
291
|
+
}
|
|
292
|
+
}
|
|
293
|
+
```
|
|
294
|
+
|
|
295
|
+
### Images in the Markdown
|
|
296
|
+
|
|
297
|
+
| `images` | effect |
|
|
298
|
+
|---|---|
|
|
299
|
+
| `'placeholder'` (default) | `<!-- image -->` marks a picture, as docling writes it |
|
|
300
|
+
| `'none'` | placeholders removed |
|
|
301
|
+
| `'extract'` | pictures come back as bytes in `data.images`, linked as `<prefix><n>.<ext>` |
|
|
302
|
+
|
|
303
|
+
With `'extract'`, `imageOptions` is required on each call, because the prefix names one document's images:
|
|
304
|
+
|
|
305
|
+
```ts
|
|
306
|
+
import { writeFile } from 'node:fs/promises';
|
|
307
|
+
|
|
308
|
+
const res = await docling.convertMarkdown(pdf, {
|
|
309
|
+
images: 'extract',
|
|
310
|
+
imageOptions: { prefix: `images/${docId}-` }, // omitSmall: drop bullets, icons and small logos, default true
|
|
311
|
+
});
|
|
312
|
+
if (res.ok) {
|
|
313
|
+
await writeFile(`out/${docId}.md`, res.data.markdown); // 
|
|
314
|
+
for (const image of res.data.images) {
|
|
315
|
+
await writeFile(`out/${image.path}`, image.bytes); // { path, mimeType, bytes, width, height }
|
|
316
|
+
}
|
|
317
|
+
}
|
|
318
|
+
```
|
|
319
|
+
|
|
320
|
+
- `n` starts at 1 and counts kept images only. `<ext>` comes from the MIME type: `png`, `jpg`, `gif`, `webp`, `svg`,
|
|
321
|
+
`tiff`, `bmp`, otherwise `bin`.
|
|
322
|
+
- `omitSmall` (default `true`) removes small pictures from the Markdown and does not return them. Small means: area
|
|
323
|
+
below 15 000 px, longer side below 200 px, or shorter side below 24 px (`isSmallImage`). Only PNGs have a known
|
|
324
|
+
size (`readPngSize`); other formats are always kept and report `width` and `height` as `0`.
|
|
325
|
+
- A picture with invalid or empty base64 data is removed and reported as an `image_not_decoded` warning
|
|
326
|
+
(`details.index`: 1-based position among all embedded pictures); the conversion still succeeds.
|
|
327
|
+
- A picture docling sent without image data keeps its `<!-- image -->` placeholder, as in `'placeholder'` mode.
|
|
328
|
+
- Removing a picture or placeholder keeps the blank line that separates the paragraphs around it.
|
|
329
|
+
|
|
330
|
+
### Warnings
|
|
331
|
+
|
|
332
|
+
`data.warnings` lists non-fatal notes. The conversion still succeeded; decide yourself whether a warning matters.
|
|
333
|
+
|
|
334
|
+
| code | `details` | meaning |
|
|
335
|
+
|---|---|---|
|
|
336
|
+
| `server` | `{ component, module, category, page }` | problem reported by docling-serve (e.g. a single page failed, `document timeout exceeded`); `page` is the 1-based PDF page, or `null` |
|
|
337
|
+
| `image_not_decoded` | `{ index }` | Markdown with `images: 'extract'` only, see above |
|
|
338
|
+
| `page_image_not_decoded` | `{ page }` | documents with `pageImages: true` only, see above |
|
|
339
|
+
|
|
340
|
+
Pages docling gave up on (e.g. `documentTimeout` exceeded) have no content. The only sign is a `server` warning per
|
|
341
|
+
failed page.
|
|
342
|
+
|
|
343
|
+
### Server versions
|
|
344
|
+
|
|
345
|
+
`data.versions` holds the versions the server reports on `GET /version`, unchanged, e.g.
|
|
346
|
+
`{ 'docling-serve': '1.36.0', docling: '2.135.0', 'docling-core': '2.101.1', … }`, or `null` if it reports none.
|
|
347
|
+
Store it with each converted document: the same PDF can convert differently under another docling version, and
|
|
348
|
+
`document.version` is the DoclingDocument schema version. Errors from a request the server answered (`http`,
|
|
349
|
+
`not_found`, `conversion_failed`, `invalid_response`) carry the same `error.versions`. Each client asks for the
|
|
350
|
+
versions once and keeps them; the request has its own 2 s limit, and when it fails `versions` is `null` and the next
|
|
351
|
+
result asks again. Create a new client after a server update.
|
|
352
|
+
|
|
353
|
+
### Conversion settings
|
|
354
|
+
|
|
355
|
+
`convert*()` results (`data.settings`) and `submit*()` jobs (`job.settings`) carry the form fields the request sent,
|
|
356
|
+
as a typed `DoclingSettings` object. The client sends an explicit value for every field it controls, also where it
|
|
357
|
+
equals docling-serve's default, so the settings do not depend on the server's defaults. Store them with the versions
|
|
358
|
+
to know how a document was converted.
|
|
359
|
+
|
|
360
|
+
```ts
|
|
361
|
+
const res = await docling.convertMarkdown(pdf, { ocrEngine: 'rapidocr' });
|
|
362
|
+
if (res.ok) {
|
|
363
|
+
res.data.settings.ocrPreset; // 'rapidocr'
|
|
364
|
+
res.data.settings.tableStructurePreset; // 'tableformer_v1_accurate'
|
|
365
|
+
res.data.settings.vlmPipelinePreset; // null: pipeline is 'standard'
|
|
366
|
+
}
|
|
367
|
+
```
|
|
368
|
+
|
|
369
|
+
- Each key is the camelCase name of a docling-serve form field (`ocrPreset` = `ocr_preset`).
|
|
370
|
+
- `null` means the field was not sent: Markdown-only fields for document output, the preset of a disabled stage,
|
|
371
|
+
unset `pageRange` and `documentTimeout`. An empty `ocrLang` was not sent either (engine default).
|
|
372
|
+
- Image input records what was sent: `doOcr: true` and `forceOcr: false`, whatever `ocr` and `forceOcr` say.
|
|
373
|
+
- Server configuration that has no request field (e.g. the layout model) is not included; see
|
|
374
|
+
`stages.layout` of the [server capabilities](#server-capabilities).
|
|
375
|
+
|
|
376
|
+
### Server capabilities
|
|
377
|
+
|
|
378
|
+
`docling.capabilities()` asks `GET /v1/capabilities` for the presets, limits and features of the server. It is for
|
|
379
|
+
diagnostics, e.g. to list the allowed `ocrEngine` ids; conversions never call it. It takes only `{ signal }`.
|
|
380
|
+
|
|
381
|
+
```ts
|
|
382
|
+
const caps = await docling.capabilities();
|
|
383
|
+
if (caps.ok) {
|
|
384
|
+
caps.data.stages.ocr?.presets.map((preset) => preset.id); // ['auto', 'easyocr', 'rapidocr', 'tesseract', …]
|
|
385
|
+
caps.data.stages.table_structure?.default; // 'tableformer_v1_accurate'
|
|
386
|
+
caps.data.limits.maxImagesScale; // 2, or null when unlimited
|
|
387
|
+
caps.data.features.apiKeyRequired; // false
|
|
388
|
+
}
|
|
389
|
+
```
|
|
390
|
+
|
|
391
|
+
- The server's snake_case keys come back in camelCase; `stages` keys stay as the server sends them (`ocr`, `layout`,
|
|
392
|
+
`table_structure`, `vlm_pipeline`, `chart_extraction`, …). Each stage has `option` (its form field), `default` and
|
|
393
|
+
`presets` (`{ id, name, description, source }`).
|
|
394
|
+
- Missing or mistyped fields become `[]`, `''`, `null` or `false`, so a newer or older payload does not fail the call.
|
|
395
|
+
- An allowed preset is not always usable: e.g. `ocrmac` only runs on macOS.
|
|
396
|
+
- An older server without the endpoint answers `http` with `status: 404`.
|
|
397
|
+
|
|
398
|
+
### Broken umlauts / special characters
|
|
399
|
+
|
|
400
|
+
If the output shows `fŸhrt`, `Nu§baum`, `…sterreich`, the PDF's text layer uses an encoding docling-parse misreads
|
|
401
|
+
(seen with `/MacRomanEncoding` PDFs from Mac Word). Re-convert that document with `{ forceOcr: true }` (with `ocrLang: ['de']` on the factory).
|
|
402
|
+
It is slower, so use it per document, not by default.
|
|
403
|
+
|
|
404
|
+
### Errors
|
|
405
|
+
|
|
406
|
+
All client calls resolve to a `Result<T>` union:
|
|
407
|
+
- `{ ok: true, data: T }` on success
|
|
408
|
+
- `{ ok: false, error: ConvertError }` on runtime failure
|
|
409
|
+
|
|
410
|
+
#### Error fields
|
|
411
|
+
|
|
412
|
+
Every `ConvertError` contains:
|
|
413
|
+
- `code`: one of the `ErrorCode` values below
|
|
414
|
+
- `message`: human-readable explanation of the failure
|
|
415
|
+
- `status`: optional HTTP status code (present when the server answered, e.g. `400`, `404`, `422`, `500`)
|
|
416
|
+
- `versions`: server versions captured from `GET /version` if the server answered, or `null`
|
|
417
|
+
- `details`: `{ errors: ServerError[]; failure: TaskFailure | null }` (present only when `code === 'conversion_failed'`)
|
|
418
|
+
|
|
419
|
+
| code | meaning |
|
|
420
|
+
|---|---|
|
|
421
|
+
| `invalid_input` | not a non-empty PDF, PNG, JPEG, TIFF or WebP `Uint8Array`, a truncated PDF (cross-reference offset past the end of the file), or not a job object from `submit*()`, or input that could not be prepared for upload (e.g. out of memory); no request sent |
|
|
422
|
+
| `network` | server unreachable (the message includes the cause, e.g. `ECONNREFUSED`) |
|
|
423
|
+
| `aborted` | your `signal` fired (incl. `AbortSignal.timeout()`) or `timeoutMs` expired |
|
|
424
|
+
| `http` | non-2xx response (`error.status` set), e.g. auth, sync wait exceeded |
|
|
425
|
+
| `not_found` | `check()`: `Unknown job id` (e.g. after a server restart), or `Result already fetched or expired`; the server's own message follows in parentheses |
|
|
426
|
+
| `conversion_failed` | the server could not convert the document, also a `partial_success` (or a success with error items) that has no Markdown or DoclingDocument |
|
|
427
|
+
| `invalid_response` | unexpected response body (no status, no Markdown or DoclingDocument without server details, a non-JSON body (quoted in the message), an unusable task id, or a body too large to read) |
|
|
428
|
+
|
|
429
|
+
`conversion_failed` adds `error.details` as `{ errors, failure }`: `errors` lists docling's error items as
|
|
430
|
+
`{ message, details }` (component, module, category, page); `failure` is docling's task classification
|
|
431
|
+
`{ category, phase, retryable }` for async jobs, or `null`.
|
|
432
|
+
|
|
433
|
+
TypeScript narrows `error` on `error.code`:
|
|
434
|
+
|
|
435
|
+
```ts
|
|
436
|
+
if (!res.ok) {
|
|
437
|
+
switch (res.error.code) {
|
|
438
|
+
case 'conversion_failed':
|
|
439
|
+
console.error('Conversion failed:', res.error.message);
|
|
440
|
+
console.error('Server error items:', res.error.details.errors);
|
|
441
|
+
console.error('Task failure:', res.error.details.failure);
|
|
442
|
+
break;
|
|
443
|
+
case 'http':
|
|
444
|
+
console.error(`HTTP error ${res.error.status}:`, res.error.message);
|
|
445
|
+
break;
|
|
446
|
+
case 'invalid_input':
|
|
447
|
+
console.error('Input rejected before request:', res.error.message);
|
|
448
|
+
break;
|
|
449
|
+
default:
|
|
450
|
+
console.error(res.error.code, res.error.message);
|
|
451
|
+
}
|
|
452
|
+
}
|
|
453
|
+
```
|
|
454
|
+
|
|
455
|
+
#### Programming errors vs runtime errors
|
|
456
|
+
|
|
457
|
+
| Error Category | Trigger | Handling |
|
|
458
|
+
|---|---|---|
|
|
459
|
+
| **Runtime failure** | Server unreachable, invalid input file bytes, server HTTP 4xx/5xx, model/conversion failure, abort signal or request timeout | Resolves to `{ ok: false, error: ConvertError }` (never throws) |
|
|
460
|
+
| **Programming error** | Invalid client config (malformed URL, invalid types), unsupported or mistyped call options, incompatible options (such as `imageOptions` without `images: 'extract'`) | Throws `TypeError` synchronously on factory; rejects with `TypeError` on async client calls before sending request |
|
|
461
|
+
|
|
462
|
+
### Exported types, utilities & constants
|
|
463
|
+
|
|
464
|
+
In addition to `createDoclingClient`, the package exports helper functions, constants, and TypeScript types:
|
|
465
|
+
|
|
466
|
+
```ts
|
|
467
|
+
import {
|
|
468
|
+
createDoclingClient,
|
|
469
|
+
toPageImageBox,
|
|
470
|
+
isSmallImage,
|
|
471
|
+
readPngSize,
|
|
472
|
+
PAGE_IMAGE_SCALE,
|
|
473
|
+
type DoclingClient,
|
|
474
|
+
type DoclingConfig,
|
|
475
|
+
type ClientOptions,
|
|
476
|
+
type DoclingOptions,
|
|
477
|
+
type MarkdownOptions,
|
|
478
|
+
type DocumentOptions,
|
|
479
|
+
type CallOptions,
|
|
480
|
+
type Result,
|
|
481
|
+
type ConvertError,
|
|
482
|
+
type ErrorCode,
|
|
483
|
+
type ConvertedMarkdown,
|
|
484
|
+
type ConvertedDocument,
|
|
485
|
+
type DoclingDocument,
|
|
486
|
+
type DocumentJob,
|
|
487
|
+
type MarkdownJob,
|
|
488
|
+
type Job,
|
|
489
|
+
type JobRef,
|
|
490
|
+
type JobState,
|
|
491
|
+
type DoclingSettings,
|
|
492
|
+
type ServerCapabilities,
|
|
493
|
+
type ExtractedImage,
|
|
494
|
+
type PageImage,
|
|
495
|
+
type PageImageBox,
|
|
496
|
+
type ImageSize,
|
|
497
|
+
type MarkdownWarning,
|
|
498
|
+
type DocumentWarning,
|
|
499
|
+
type ServerError,
|
|
500
|
+
type TaskFailure,
|
|
501
|
+
} from 'docling-serve-client';
|
|
502
|
+
```
|
|
503
|
+
|
|
504
|
+
- `toPageImageBox(document, prov)`: maps a provenance item `{ page_no, bbox }` to `{ page, x, y, width, height }` in pixels with a top-left origin; returns `undefined` if the page is missing or coordinates are invalid.
|
|
505
|
+
- `isSmallImage(size)`: returns `true` if pixel dimensions match the `omitSmall` filter (area < 15,000 px, long side < 200 px, or short side < 24 px).
|
|
506
|
+
- `readPngSize(bytes)`: parses `{ width, height }` directly from a PNG's IHDR header; returns `undefined` if not a valid PNG.
|
|
507
|
+
- `PAGE_IMAGE_SCALE`: constant `2` (144 dpi resolution used by docling page images and bounding box coordinates).
|
|
508
|
+
|
|
509
|
+
## Running docling-serve
|
|
510
|
+
|
|
511
|
+
The client connects to a running [docling-serve](https://github.com/docling-project/docling-serve) server:
|
|
512
|
+
|
|
513
|
+
```bash
|
|
514
|
+
# Install docling-serve (default / CPU)
|
|
515
|
+
uv tool install docling-serve
|
|
516
|
+
|
|
517
|
+
# Or with CUDA (check your driver with nvidia-smi; use matching PyTorch tag, e.g. cu124, cu126)
|
|
518
|
+
uv tool install --torch-backend <cuda-tag> docling-serve
|
|
519
|
+
|
|
520
|
+
# Or via Docker (CPU)
|
|
521
|
+
docker run -p 5001:5001 quay.io/ds4sd/docling-serve
|
|
522
|
+
|
|
523
|
+
# Or via Docker (NVIDIA GPU / CUDA)
|
|
524
|
+
docker run --gpus all -p 5001:5001 quay.io/ds4sd/docling-serve
|
|
525
|
+
|
|
526
|
+
# Start the local server (listens on http://127.0.0.1:5001 by default)
|
|
527
|
+
docling-serve run
|
|
528
|
+
```
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
import type { Result, ServerCapabilities } from './types.js';
|
|
2
|
+
/**
|
|
3
|
+
* **Maps the `GET /v1/capabilities` payload to camelCase `ServerCapabilities`**.
|
|
4
|
+
*
|
|
5
|
+
* - lenient per field: missing or mistyped values become `[]`, `''`, `null` or `false`, so new server fields or
|
|
6
|
+
* removed ones never fail the call
|
|
7
|
+
* - non-object body: `invalid_response`
|
|
8
|
+
*/
|
|
9
|
+
export declare function readCapabilities(body: unknown): Result<ServerCapabilities>;
|
|
10
|
+
//# sourceMappingURL=capabilities.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../src/capabilities.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAuD,MAAM,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAalH;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,CAAC,kBAAkB,CAAC,CA0B1E"}
|
package/dist/client.d.ts
ADDED
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
import type { DoclingClient, DoclingConfig } from './types.js';
|
|
2
|
+
/**
|
|
3
|
+
* **docling-serve client factory**.
|
|
4
|
+
*
|
|
5
|
+
* - validates configuration once; its only state is the cached server versions
|
|
6
|
+
* - returned functions resolve to `Result`; invalid options reject with a `TypeError` before any request
|
|
7
|
+
* - `timeoutMs` limits every request except `/version`, which has its own limit
|
|
8
|
+
* @throws `TypeError` on invalid configuration.
|
|
9
|
+
*/
|
|
10
|
+
export declare function createDoclingClient(config: DoclingConfig): DoclingClient;
|
|
11
|
+
//# sourceMappingURL=client.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAKR,aAAa,EACb,aAAa,EAUhB,MAAM,YAAY,CAAC;AAwEpB;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,aAAa,GAAG,aAAa,CAgQxE"}
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
import type { Result } from '../types.js';
|
|
2
|
+
/**
|
|
3
|
+
* **Executes `fetch` and parses the JSON body into a `Result`**.
|
|
4
|
+
*
|
|
5
|
+
* - non-2xx: `http` with FastAPI `detail`; unparsable 2xx body: `invalid_response`
|
|
6
|
+
* - body too large for a string or for memory: `invalid_response`, as a retry fails the same way
|
|
7
|
+
* - aborted signal: `aborted`; anything else thrown: `network`
|
|
8
|
+
*/
|
|
9
|
+
export declare function fetchJson(fetchFn: typeof fetch, url: string, init: RequestInit): Promise<Result<unknown>>;
|
|
10
|
+
/** Extracts message, appending `cause.message` if present. */
|
|
11
|
+
export declare function errorMessage(e: unknown): string;
|
|
12
|
+
//# sourceMappingURL=http.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../src/core/http.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAuB1C;;;;;;GAMG;AACH,wBAAsB,SAAS,CAAC,OAAO,EAAE,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAmB/G;AAED,8DAA8D;AAC9D,wBAAgB,YAAY,CAAC,CAAC,EAAE,OAAO,GAAG,MAAM,CAK/C"}
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
/** Detected input format and how it is sent to docling-serve. */
|
|
2
|
+
export type InputFormat = {
|
|
3
|
+
/** docling's `from_formats` value. */
|
|
4
|
+
fromFormat: 'pdf' | 'image';
|
|
5
|
+
/** MIME type of the multipart file part. */
|
|
6
|
+
mimeType: string;
|
|
7
|
+
/** File name of the multipart file part; docling reads the format from its extension. */
|
|
8
|
+
fileName: string;
|
|
9
|
+
};
|
|
10
|
+
/**
|
|
11
|
+
* **Detects the input format by magic bytes**.
|
|
12
|
+
*
|
|
13
|
+
* - image signatures must start at byte 0; PDF: `%PDF-` within the first 1024 bytes
|
|
14
|
+
* - images are checked first, so an image whose data happens to contain `%PDF-` is still an image
|
|
15
|
+
* - returns `undefined` for empty, non-`Uint8Array` or unrecognized input
|
|
16
|
+
*/
|
|
17
|
+
export declare function detectInputFormat(bytes: unknown): InputFormat | undefined;
|
|
18
|
+
//# sourceMappingURL=input.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"input.d.ts","sourceRoot":"","sources":["../../src/core/input.ts"],"names":[],"mappings":"AASA,iEAAiE;AACjE,MAAM,MAAM,WAAW,GAAG;IACtB,sCAAsC;IACtC,UAAU,EAAE,KAAK,GAAG,OAAO,CAAC;IAC5B,4CAA4C;IAC5C,QAAQ,EAAE,MAAM,CAAC;IACjB,yFAAyF;IACzF,QAAQ,EAAE,MAAM,CAAC;CACpB,CAAC;AAuCF;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,WAAW,GAAG,SAAS,CAWzE"}
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
/** Matches a `%PDF-` header starting within the first 1024 bytes. */
|
|
2
|
+
export declare function isPdf(bytes: unknown): bytes is Uint8Array;
|
|
3
|
+
/**
|
|
4
|
+
* **Returns cross-reference offset if PDF is truncated**: last `startxref` points at or past EOF.
|
|
5
|
+
*
|
|
6
|
+
* - typical for aborted downloads; docling then fails with a vague load error
|
|
7
|
+
* - only the last 2 KB are read, as latin1
|
|
8
|
+
* - returns `undefined` when offset lies inside file or no `startxref` found
|
|
9
|
+
*/
|
|
10
|
+
export declare function findTruncatedXref(bytes: Uint8Array): number | undefined;
|
|
11
|
+
//# sourceMappingURL=pdf.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"pdf.d.ts","sourceRoot":"","sources":["../../src/core/pdf.ts"],"names":[],"mappings":"AAoBA,qEAAqE;AACrE,wBAAgB,KAAK,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,UAAU,CAkBzD;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,GAAG,SAAS,CAKvE"}
|