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.
Files changed (44) hide show
  1. package/LICENSE +201 -0
  2. package/README.md +527 -2
  3. package/dist/capabilities.d.ts +10 -0
  4. package/dist/capabilities.d.ts.map +1 -0
  5. package/dist/client.d.ts +11 -0
  6. package/dist/client.d.ts.map +1 -0
  7. package/dist/core/http.d.ts +12 -0
  8. package/dist/core/http.d.ts.map +1 -0
  9. package/dist/core/input.d.ts +18 -0
  10. package/dist/core/input.d.ts.map +1 -0
  11. package/dist/core/pdf.d.ts +11 -0
  12. package/dist/core/pdf.d.ts.map +1 -0
  13. package/dist/core/result.d.ts +54 -0
  14. package/dist/core/result.d.ts.map +1 -0
  15. package/dist/core/validate.d.ts +29 -0
  16. package/dist/core/validate.d.ts.map +1 -0
  17. package/dist/document.d.ts +412 -0
  18. package/dist/document.d.ts.map +1 -0
  19. package/dist/images.d.ts +70 -0
  20. package/dist/images.d.ts.map +1 -0
  21. package/dist/index.d.ts +6 -0
  22. package/dist/index.d.ts.map +1 -0
  23. package/dist/index.js +968 -0
  24. package/dist/index.js.map +19 -0
  25. package/dist/options.d.ts +64 -0
  26. package/dist/options.d.ts.map +1 -0
  27. package/dist/response.d.ts +27 -0
  28. package/dist/response.d.ts.map +1 -0
  29. package/dist/types.d.ts +459 -0
  30. package/dist/types.d.ts.map +1 -0
  31. package/package.json +74 -4
  32. package/src/capabilities.ts +109 -0
  33. package/src/client.ts +480 -0
  34. package/src/core/http.ts +96 -0
  35. package/src/core/input.ts +75 -0
  36. package/src/core/pdf.ts +54 -0
  37. package/src/core/result.ts +54 -0
  38. package/src/core/validate.ts +85 -0
  39. package/src/document.ts +417 -0
  40. package/src/images.ts +337 -0
  41. package/src/index.ts +69 -0
  42. package/src/options.ts +350 -0
  43. package/src/response.ts +218 -0
  44. package/src/types.ts +513 -0
package/README.md CHANGED
@@ -1,3 +1,528 @@
1
- # Temporary Holding Version
1
+ [![Test](https://github.com/martin-winkler-dev/docling-serve-client-js/actions/workflows/test.yml/badge.svg)](https://github.com/martin-winkler-dev/docling-serve-client-js/actions/workflows/test.yml)
2
+ [![Package](https://github.com/martin-winkler-dev/docling-serve-client-js/actions/workflows/package.yml/badge.svg)](https://github.com/martin-winkler-dev/docling-serve-client-js/actions/workflows/package.yml)
3
+ [![Bun](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2Fmartin-winkler-dev%2Fdocling-serve-client-js%2Fmain%2Fpackage.json&query=%24.engines.bun&label=Bun&logo=bun&color=blue)](https://bun.sh)
4
+ [![Node.js](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2Fmartin-winkler-dev%2Fdocling-serve-client-js%2Fmain%2Fpackage.json&query=%24.engines.node&label=Node.js&logo=nodedotjs&color=blue)](https://nodejs.org)
5
+ [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
2
6
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
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); // ![Image](images/1234-1.png)
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"}
@@ -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"}