docling-serve-client 0.4.0 → 0.6.0

package/src/client.ts

@@ -1,18 +1,25 @@
 // Copyright 2026 Martin Winkler
 // SPDX-License-Identifier: Apache-2.0
 
+import { readCapabilities } from './capabilities.js';
 import { errorMessage, fetchJson } from './core/http.js';
 import { detectInputFormat, type InputFormat } from './core/input.js';
 import { findTruncatedXref } from './core/pdf.js';
 import { ERR, fail, ok } from './core/result.js';
 import { PAGE_IMAGE_SCALE } from './images.js';
 import {
+    type DocumentCall,
     isJobId,
+    type MarkdownCall,
+    type PollCall,
     type ResolvedOptions,
     resolveCheckOptions,
     resolveConfig,
     resolveDocumentCall,
     resolveMarkdownCall,
+    resolvePollOptions,
+    resolveRunDocumentCall,
+    resolveRunMarkdownCall,
     validateJob,
 } from './options.js';
 import { type DoclingFailureInfo, readDocument, readFailure, readMarkdown, readText } from './response.js';
@@ -23,12 +30,15 @@ import type {
     ConvertInput,
     DoclingClient,
     DoclingConfig,
+    DoclingSettings,
     DocumentJob,
-    Job,
+    JobRef,
     JobState,
     MarkdownJob,
     Result,
+    ServerCapabilities,
     ServerVersions,
+    WithSettings,
 } from './types.js';
 
 // -------------------------------------------------------------------
@@ -55,15 +65,30 @@ type FormatFields = {
     pageImages: boolean;
 };
 
+/** Parsed JSON answer of a conversion POST, with the settings its form was built from. */
+type Posted = {
+    body: unknown;
+    settings: DoclingSettings;
+};
+
 // -------------------------------------------------------------------
 // --- 2. Constants
 // -------------------------------------------------------------------
 
-/** Fixed conversion form fields sent with every request. */
-const FIXED_FORM_FIELDS: [name: string, value: string][] = [
-    ['do_table_structure', 'true'],
-    ['table_mode', 'accurate'],
-];
+/** Table structure model; pinned so the server's fallback preset cannot change table output. */
+const TABLE_STRUCTURE_PRESET = 'tableformer_v1_accurate';
+
+/** Model of `pipeline: 'vlm'`. */
+const VLM_PIPELINE_PRESET = 'granite_docling';
+
+/** Model of `chartExtraction`. */
+const CHART_EXTRACTION_PRESET = 'granite_vision_v4';
+
+/** Model of `formulaEnrichment` and `codeEnrichment`. */
+const CODE_FORMULA_PRESET = 'codeformulav2';
+
+/** Matches each upper-case letter of a camelCase settings key, for its snake_case form field name. */
+const MATCH_UPPER_CASE = /[A-Z]/g;
 
 /** Error message for missing, empty or unrecognized input bytes. */
 const INVALID_INPUT = 'Expected a non-empty PDF, PNG, JPEG, TIFF or WebP as Uint8Array';
@@ -89,13 +114,14 @@ const MAX_SHOWN_ID_LENGTH = 100;
 /**
  * **docling-serve client factory**.
  *
- * - validates configuration once; its only state is the cached server versions
- * - returned functions resolve to `Result`; invalid options reject with a `TypeError` before any request
+ * - validates configuration once; its only state is cached server versions
+ * - returned functions resolve to `Result`; invalid options reject with `TypeError` before any request
  * - `timeoutMs` limits every request except `/version`, which has its own limit
+ * - `pollMs` sets default delay between job helper status polls, overridable per call
  * @throws `TypeError` on invalid configuration.
  */
 export function createDoclingClient(config: DoclingConfig): DoclingClient {
-    const { baseUrl, apiKey, fetch: fetchFn, timeoutMs, defaults } = resolveConfig(config);
+    const { baseUrl, apiKey, fetch: fetchFn, timeoutMs, pollMs, defaults } = resolveConfig(config);
     const headers: Record<string, string> = apiKey === undefined ? {} : { 'X-Api-Key': apiKey };
     /** Pending or resolved `/version` answer shared by all calls of this client. */
     let versionsCache: Promise<ServerVersions | null> | undefined;
@@ -106,18 +132,32 @@ export function createDoclingClient(config: DoclingConfig): DoclingClient {
         submitMarkdown,
         submitDocument,
         check: check as DoclingClient['check'],
+        runMarkdown,
+        runDocument,
+        waitForJob: waitForJob as DoclingClient['waitForJob'],
+        capabilities,
     };
 
     /** Converts PDF or image bytes to md in one request. */
-    async function convertMarkdown(input: ConvertInput, options?: unknown): Promise<Result<ConvertedMarkdown>> {
+    async function convertMarkdown(
+        input: ConvertInput,
+        options?: unknown,
+    ): Promise<Result<WithSettings<ConvertedMarkdown>>> {
         const call = resolveMarkdownCall(defaults, options);
         const fields: FormatFields = { format: 'md', embedImages: call.output.images === 'extract', pageImages: false };
         const res = await post('/v1/convert/file', input, call.options, fields, call.signal);
-        return res.ok ? withVersions(readMarkdown(res.data, call.output)) : res;
+        if (!res.ok) {
+            return res;
+        }
+        const converted = await withVersions<ConvertedMarkdown>(readMarkdown(res.data.body, call.output));
+        return converted.ok ? ok({ ...converted.data, settings: res.data.settings }) : converted;
     }
 
     /** Converts PDF or image bytes to a DoclingDocument in one request. */
-    async function convertDocument(input: ConvertInput, options?: unknown): Promise<Result<ConvertedDocument>> {
+    async function convertDocument(
+        input: ConvertInput,
+        options?: unknown,
+    ): Promise<Result<WithSettings<ConvertedDocument>>> {
         const call = resolveDocumentCall(defaults, options);
         const fields: FormatFields = {
             format: 'json',
@@ -125,46 +165,126 @@ export function createDoclingClient(config: DoclingConfig): DoclingClient {
             pageImages: call.pageImages,
         };
         const res = await post('/v1/convert/file', input, call.options, fields, call.signal);
-        return res.ok ? withVersions(readDocument(res.data)) : res;
+        if (!res.ok) {
+            return res;
+        }
+        const converted = await withVersions<ConvertedDocument>(readDocument(res.data.body));
+        return converted.ok ? ok({ ...converted.data, settings: res.data.settings }) : converted;
     }
 
-    /** Starts an async md conversion; the job carries the image handling for `check`. */
+    /** Starts an async md conversion; the job carries the image handling for `check` and the sent settings. */
     async function submitMarkdown(input: ConvertInput, options?: unknown): Promise<Result<MarkdownJob>> {
         const call = resolveMarkdownCall(defaults, options);
-        const fields: FormatFields = { format: 'md', embedImages: call.output.images === 'extract', pageImages: false };
-        const id = await submit(input, call.options, fields, call.signal);
-        return id.ok ? ok({ kind: 'markdown', id: id.data, output: call.output }) : id;
+        return await startMarkdownJob(input, call);
     }
 
     /** Starts an async document conversion; page images need no job field, `check` moves any it finds. */
     async function submitDocument(input: ConvertInput, options?: unknown): Promise<Result<DocumentJob>> {
         const call = resolveDocumentCall(defaults, options);
+        return await startDocumentJob(input, call);
+    }
+
+    /** Submits an md job and polls it until done; resolves like `convertMarkdown`, with the job's settings. */
+    async function runMarkdown(
+        input: ConvertInput,
+        options?: unknown,
+    ): Promise<Result<WithSettings<ConvertedMarkdown>>> {
+        const call = resolveRunMarkdownCall(defaults, pollMs, options);
+        const job = await startMarkdownJob(input, call);
+        if (!job.ok) {
+            return job;
+        }
+        const done = await pollUntilDone<ConvertedMarkdown>(job.data, call);
+        return done.ok ? ok({ ...done.data, settings: job.data.settings }) : done;
+    }
+
+    /** Submits a document job and polls it until done; resolves like `convertDocument`, with the job's settings. */
+    async function runDocument(
+        input: ConvertInput,
+        options?: unknown,
+    ): Promise<Result<WithSettings<ConvertedDocument>>> {
+        const call = resolveRunDocumentCall(defaults, pollMs, options);
+        const job = await startDocumentJob(input, call);
+        if (!job.ok) {
+            return job;
+        }
+        const done = await pollUntilDone<ConvertedDocument>(job.data, call);
+        return done.ok ? ok({ ...done.data, settings: job.data.settings }) : done;
+    }
+
+    /** Polls an existing job until done; the job is validated and copied once, so later changes to it have no effect. */
+    async function waitForJob(job: JobRef, options?: unknown): Promise<Result<ConvertedMarkdown | ConvertedDocument>> {
+        const call = resolvePollOptions(pollMs, options);
+        const valid = validateJob(job);
+        return valid.ok ? pollUntilDone(valid.data, call) : valid;
+    }
+
+    /** Posts an md job for a validated call. */
+    async function startMarkdownJob(input: ConvertInput, call: MarkdownCall): Promise<Result<MarkdownJob>> {
+        const fields: FormatFields = { format: 'md', embedImages: call.output.images === 'extract', pageImages: false };
+        const task = await submit(input, call.options, fields, call.signal);
+        return task.ok
+            ? ok({ kind: 'markdown', id: task.data.id, output: call.output, settings: task.data.settings })
+            : task;
+    }
+
+    /** Posts a document job for a validated call. */
+    async function startDocumentJob(input: ConvertInput, call: DocumentCall): Promise<Result<DocumentJob>> {
         const fields: FormatFields = {
             format: 'json',
             embedImages: call.images === 'embedded',
             pageImages: call.pageImages,
         };
-        const id = await submit(input, call.options, fields, call.signal);
-        return id.ok ? ok({ kind: 'document', id: id.data }) : id;
+        const task = await submit(input, call.options, fields, call.signal);
+        return task.ok ? ok({ kind: 'document', id: task.data.id, settings: task.data.settings }) : task;
     }
 
     /**
-     * **Polls a job and fetches its result when done**.
+     * **Polls a job until done**: waits `pollMs` after each `queued` or `running` status.
      *
-     * - unknown job id: `not_found` with `Unknown job id`
-     * - result fetched more than `DOCLING_SERVE_RESULT_REMOVAL_DELAY` (default 300 s) ago or expired: `not_found` with
-     *   `Result already fetched or expired`
+     * - `job` must be validated: it is polled as is, without a new check per poll
+     * - first poll runs immediately; at most one request in flight
+     * - resolves to `done` result without `status`, or first error unchanged
+     * - abort during wait resolves to `aborted` immediately; abort during request returns request error
      */
+    async function pollUntilDone<T>(job: JobRef, { pollMs: waitMs, signal }: PollCall): Promise<Result<T>> {
+        for (;;) {
+            const state = await fetchJobState(job, signal);
+            if (!state.ok) {
+                return state;
+            }
+            if (state.data.status === 'done') {
+                const { status: _done, ...result } = state.data;
+                return ok(result as T);
+            }
+            if (!(await sleep(waitMs, signal))) {
+                return fail(ERR.ABORTED(`Aborted while waiting for job ${job.id}`));
+            }
+        }
+    }
+
+    /** Polls a job and fetches its result when done; a malformed job is `invalid_input` without a request. */
     async function check(
-        job: Job,
+        job: JobRef,
         options?: unknown,
     ): Promise<Result<JobState<ConvertedMarkdown | ConvertedDocument>>> {
         const { signal } = resolveCheckOptions(options);
         const valid = validateJob(job);
-        if (!valid.ok) {
-            return valid;
-        }
-        const { id } = valid.data;
+        return valid.ok ? fetchJobState(valid.data, signal) : valid;
+    }
+
+    /**
+     * **Status request for a validated job; result download when done**.
+     *
+     * - unknown job id: `not_found` with `Unknown job id`; also once docling-serve deleted the task,
+     *   `DOCLING_SERVE_RESULT_REMOVAL_DELAY` (default 300 s) after the first result fetch
+     * - task deleted between the status poll and the result fetch: `not_found` with `Result already fetched or expired`
+     */
+    async function fetchJobState(
+        job: JobRef,
+        signal: AbortSignal | undefined,
+    ): Promise<Result<JobState<ConvertedMarkdown | ConvertedDocument>>> {
+        const { id } = job;
         const res = await get(`/v1/status/poll/${id}`, signal);
         if (!res.ok) {
             const error =
@@ -191,9 +311,8 @@ export function createDoclingClient(config: DoclingConfig): DoclingClient {
                             : result.error;
                     return failWithVersions(error);
                 }
-                const checked = valid.data;
                 const output =
-                    checked.kind === 'markdown' ? readMarkdown(result.data, checked.output) : readDocument(result.data);
+                    job.kind === 'markdown' ? readMarkdown(result.data, job.output) : readDocument(result.data);
                 const done = await withVersions<ConvertedMarkdown | ConvertedDocument>(output);
                 return done.ok ? ok({ status: 'done', ...done.data }) : done;
             }
@@ -209,18 +328,33 @@ export function createDoclingClient(config: DoclingConfig): DoclingClient {
         }
     }
 
-    /** Posts the input to the async endpoint; resolves to the task id. */
+    /**
+     * **Queries `GET /v1/capabilities` on demand**.
+     *
+     * - older servers without the endpoint answer `http` (404)
+     */
+    async function capabilities(options?: unknown): Promise<Result<ServerCapabilities>> {
+        const { signal } = resolveCheckOptions(options);
+        const res = await get('/v1/capabilities', signal);
+        if (!res.ok) {
+            return failWithVersions(res.error);
+        }
+        const read = readCapabilities(res.data);
+        return read.ok ? read : failWithVersions(read.error);
+    }
+
+    /** Posts the input to the async endpoint; resolves to the task id and the sent settings. */
     async function submit(
         input: ConvertInput,
         options: ResolvedOptions,
         fields: FormatFields,
         signal: AbortSignal | undefined,
-    ): Promise<Result<string>> {
+    ): Promise<Result<{ id: string; settings: DoclingSettings }>> {
         const res = await post('/v1/convert/file/async', input, options, fields, signal);
         if (!res.ok) {
             return res;
         }
-        const id: unknown = (res.data as DoclingTaskStatus | null)?.task_id;
+        const id: unknown = (res.data.body as DoclingTaskStatus | null)?.task_id;
         if (readText(id) === undefined) {
             return failWithVersions(ERR.INVALID_RESPONSE('Response has no task_id'));
         }
@@ -228,7 +362,7 @@ export function createDoclingClient(config: DoclingConfig): DoclingClient {
             const shown = JSON.stringify(id).slice(0, MAX_SHOWN_ID_LENGTH);
             return failWithVersions(ERR.INVALID_RESPONSE(`Response has an unusable task_id: ${shown}`));
         }
-        return ok(id);
+        return ok({ id, settings: res.data.settings });
     }
 
     /** Detects and checks the input format, then sends a multipart POST with timeout; errors already carry versions. */
@@ -238,14 +372,15 @@ export function createDoclingClient(config: DoclingConfig): DoclingClient {
         options: ResolvedOptions,
         fields: FormatFields,
         signal: AbortSignal | undefined,
-    ): Promise<Result<unknown>> {
+    ): Promise<Result<Posted>> {
         const format = readInputFormat(input);
         if (!format.ok) {
             return format;
         }
+        const settings = buildSettings(format.data, options, fields);
         let body: FormData;
         try {
-            body = buildFormData(input, format.data, options, fields);
+            body = buildFormData(input, format.data, settings);
         } catch (error) {
             return fail(ERR.INVALID_INPUT(`Input could not be prepared for upload: ${errorMessage(error)}`));
         }
@@ -256,7 +391,7 @@ export function createDoclingClient(config: DoclingConfig): DoclingClient {
             body,
             ...(limited === undefined ? {} : { signal: limited }),
         });
-        return res.ok ? res : failWithVersions(res.error);
+        return res.ok ? ok({ body: res.data, settings }) : failWithVersions(res.error);
     }
 
     /** GET request; `limit: false` skips `timeoutMs` (used by `/version`). */
@@ -320,9 +455,33 @@ export function createDoclingClient(config: DoclingConfig): DoclingClient {
 }
 
 // -------------------------------------------------------------------
-// --- 4. Internal Functions
+// --- 4. Private Functions
 // -------------------------------------------------------------------
 
+/**
+ * **Waits `ms` unless `signal` aborts**.
+ *
+ * - resolves `true` after the wait, `false` at once on abort (also when already aborted)
+ * - clears its timer and removes its listener either way
+ */
+function sleep(ms: number, signal: AbortSignal | undefined): Promise<boolean> {
+    if (signal?.aborted) {
+        return Promise.resolve(false);
+    }
+    return new Promise((resolve) => {
+        const timer = setTimeout(() => {
+            signal?.removeEventListener('abort', onAbort);
+            resolve(true);
+        }, ms);
+        /** Ends the wait early. */
+        function onAbort() {
+            clearTimeout(timer);
+            resolve(false);
+        }
+        signal?.addEventListener('abort', onAbort, { once: true });
+    });
+}
+
 /** Caller signal combined with a `timeoutMs` limit; either alone when the other is unset. */
 function withTimeout(signal: AbortSignal | undefined, timeoutMs: number | undefined): AbortSignal | undefined {
     if (timeoutMs === undefined) {
@@ -354,60 +513,74 @@ function readInputFormat(input: unknown): Result<InputFormat> {
 }
 
 /**
- * **Builds the multipart body**: input file, fixed fields, output format and every docling option explicitly.
+ * **Every form field of a conversion request, as typed settings**.
  *
- * - input: `from_formats` (`pdf` or `image`) with a matching file name and MIME type
- * - md: `md_compact_tables=true`, no page break placeholder
+ * - md: `md_compact_tables=true`, empty page break placeholder; json sends neither
  * - images: `image_export_mode=embedded` when picture data or page images are requested, else `placeholder`;
  *   `include_images` and `include_page_images` pick which data docling sends
  * - `images_scale` fixed at `PAGE_IMAGE_SCALE`; it sets picture and page image resolution only, OCR has its own scale
+ * - PDF input: `forceOcr` enables OCR even with `ocr: false` (docling skips `force_ocr` when `do_ocr=false`)
  * - image input: OCR always on and never full-page, whatever `ocr` and `forceOcr` say
+ * - model presets pinned; a preset of a disabled stage is not sent
+ * - fields docling-serve would default silently are sent with that default
  */
-function buildFormData(
-    input: ConvertInput,
-    { fromFormat, mimeType, fileName }: InputFormat,
+function buildSettings(
+    { fromFormat }: InputFormat,
     options: ResolvedOptions,
     { format, embedImages, pageImages }: FormatFields,
-): FormData {
+): DoclingSettings {
+    const isImage = fromFormat === 'image';
+    const isMarkdown = format === 'md';
+    return {
+        fromFormats: fromFormat,
+        toFormats: format,
+        imageExportMode: embedImages || pageImages ? 'embedded' : 'placeholder',
+        includeImages: embedImages,
+        includePageImages: pageImages,
+        imagesScale: PAGE_IMAGE_SCALE,
+        mdCompactTables: isMarkdown ? true : null,
+        mdPageBreakPlaceholder: isMarkdown ? '' : null,
+        doOcr: isImage || options.ocr || options.forceOcr,
+        forceOcr: !isImage && options.forceOcr,
+        ocrPreset: options.ocrEngine,
+        ocrLang: [...(options.ocrLang ?? [])],
+        pdfBackend: options.pdfBackend,
+        pipeline: options.pipeline,
+        vlmPipelinePreset: options.pipeline === 'vlm' ? VLM_PIPELINE_PRESET : null,
+        doTableStructure: true,
+        tableMode: 'accurate',
+        tableStructurePreset: TABLE_STRUCTURE_PRESET,
+        tableCellMatching: true,
+        doPdfHeadingHierarchy: options.headingHierarchy,
+        doFormulaEnrichment: options.formulaEnrichment,
+        doCodeEnrichment: options.codeEnrichment,
+        codeFormulaPreset: options.formulaEnrichment || options.codeEnrichment ? CODE_FORMULA_PRESET : null,
+        doChartExtraction: options.chartExtraction,
+        chartExtractionPreset: options.chartExtraction ? CHART_EXTRACTION_PRESET : null,
+        doPictureClassification: false,
+        doPictureDescription: false,
+        pageRange: options.pageRange === undefined ? null : [options.pageRange[0], options.pageRange[1]],
+        documentTimeout: options.documentTimeout ?? null,
+        abortOnError: false,
+    };
+}
+
+/**
+ * **Builds the multipart body from the settings, so sent fields and returned settings cannot differ**.
+ *
+ * - field name: settings key in snake_case (`ocrPreset` → `ocr_preset`)
+ * - `null` not sent; lists as repeated fields (empty list: not sent); booleans and numbers as strings
+ * - input: file name and MIME type matching `from_formats`
+ */
+function buildFormData(input: ConvertInput, { mimeType, fileName }: InputFormat, settings: DoclingSettings): FormData {
     const form = new FormData();
-    // Blob does not accept SharedArrayBuffer-backed input: copy only that into a fresh ArrayBuffer.
     const bytes = input.buffer instanceof ArrayBuffer ? (input as Uint8Array<ArrayBuffer>) : new Uint8Array(input);
     form.append('files', new Blob([bytes], { type: mimeType }), fileName);
-    form.append('from_formats', fromFormat);
-    for (const [name, value] of FIXED_FORM_FIELDS) {
-        form.append(name, value);
-    }
-    form.append('to_formats', format);
-    if (format === 'md') {
-        form.append('md_compact_tables', 'true');
-    }
-    form.append('include_images', String(embedImages));
-    form.append('include_page_images', String(pageImages));
-    form.append('image_export_mode', embedImages || pageImages ? 'embedded' : 'placeholder');
-    form.append('images_scale', String(PAGE_IMAGE_SCALE));
-    form.append('do_pdf_heading_hierarchy', String(options.headingHierarchy));
-    form.append('do_formula_enrichment', String(options.formulaEnrichment));
-    form.append('do_code_enrichment', String(options.codeEnrichment));
-    if (options.formulaEnrichment || options.codeEnrichment) {
-        form.append('code_formula_preset', 'codeformulav2');
-    }
-    form.append('do_chart_extraction', String(options.chartExtraction));
-    form.append('pipeline', options.pipeline);
-    form.append('pdf_backend', options.pdfBackend);
-    // an image has no text layer: without OCR it yields no text, and full-page OCR merges its words
-    const isImage = fromFormat === 'image';
-    form.append('do_ocr', String(isImage || options.ocr));
-    form.append('force_ocr', String(!isImage && options.forceOcr));
-    // lists are sent as repeated fields
-    for (const lang of options.ocrLang ?? []) {
-        form.append('ocr_lang', lang);
-    }
-    if (options.pageRange !== undefined) {
-        form.append('page_range', String(options.pageRange[0]));
-        form.append('page_range', String(options.pageRange[1]));
-    }
-    if (options.documentTimeout !== undefined) {
-        form.append('document_timeout', String(options.documentTimeout));
+    for (const [key, value] of Object.entries(settings)) {
+        const name = key.replace(MATCH_UPPER_CASE, (letter) => `_${letter.toLowerCase()}`);
+        for (const item of value === null ? [] : Array.isArray(value) ? value : [value]) {
+            form.append(name, String(item));
+        }
     }
     return form;
 }

package/src/core/http.ts

@@ -61,7 +61,7 @@ export function errorMessage(e: unknown): string {
 }
 
 // -------------------------------------------------------------------
-// --- 3. Internal Functions
+// --- 3. Private Functions
 // -------------------------------------------------------------------
 
 /** Checks whether an error indicates body size exceeded memory or maximum string length. */
@@ -89,8 +89,6 @@ function errorDetail(text: string): string {
             const { detail } = body;
             return typeof detail === 'string' ? detail : JSON.stringify(detail);
         }
-    } catch {
-        // Not JSON: fall back to raw text
-    }
+    } catch {}
     return text.slice(0, 500) || 'no response body';
 }

package/src/core/input.ts

@@ -33,10 +33,8 @@ type ImageSignature = {
 const IMAGE_SIGNATURES: readonly ImageSignature[] = [
     { mimeType: 'image/png', extension: 'png', parts: [[0, [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]]] },
     { mimeType: 'image/jpeg', extension: 'jpg', parts: [[0, [0xff, 0xd8, 0xff]]] },
-    // little-endian `II*\0` and big-endian `MM\0*`
     { mimeType: 'image/tiff', extension: 'tiff', parts: [[0, [0x49, 0x49, 0x2a, 0x00]]] },
     { mimeType: 'image/tiff', extension: 'tiff', parts: [[0, [0x4d, 0x4d, 0x00, 0x2a]]] },
-    // `RIFF` <size> `WEBP`
     {
         mimeType: 'image/webp',
         extension: 'webp',
@@ -59,7 +57,7 @@ const PDF_FORMAT: InputFormat = { fromFormat: 'pdf', mimeType: 'application/pdf'
  *
  * - image signatures must start at byte 0; PDF: `%PDF-` within the first 1024 bytes
  * - images are checked first, so an image whose data happens to contain `%PDF-` is still an image
- * @returns `undefined` for empty, non-`Uint8Array` or unrecognized input
+ * - returns `undefined` for empty, non-`Uint8Array` or unrecognized input
  */
 export function detectInputFormat(bytes: unknown): InputFormat | undefined {
     if (!(bytes instanceof Uint8Array) || bytes.length === 0) {

package/src/core/pdf.ts

@@ -25,7 +25,6 @@ export function isPdf(bytes: unknown): bytes is Uint8Array {
     }
     const head = bytes.subarray(0, HEADER_SEARCH_LENGTH);
     for (let i = 0; i + 5 <= head.length; i++) {
-        // %PDF-
         if (
             head[i] === 0x25 &&
             head[i + 1] === 0x50 &&
@@ -40,11 +39,11 @@ export function isPdf(bytes: unknown): bytes is Uint8Array {
 }
 
 /**
- * **Returns cross-reference offset if PDF is truncated**: last 'startxref' points at or past EOF.
+ * **Returns cross-reference offset if PDF is truncated**: last `startxref` points at or past EOF.
  *
  * - typical for aborted downloads; docling then fails with a vague load error
  * - only the last 2 KB are read, as latin1
- * - returns 'undefined' when offset lies inside file or no 'startxref' found
+ * - returns `undefined` when offset lies inside file or no `startxref` found
  */
 export function findTruncatedXref(bytes: Uint8Array): number | undefined {
     const tail = new TextDecoder('latin1').decode(bytes.subarray(Math.max(0, bytes.length - TAIL_LENGTH)));

package/src/core/validate.ts

@@ -47,7 +47,6 @@ export function validateKeys<T extends object>(
         }
         valid[name] = Array.isArray(value) ? [...value] : value;
     }
-    // Every key was checked against its rule above.
     return valid as Partial<T>;
 }
 
@@ -74,12 +73,12 @@ export function isPlainObject(value: unknown): value is Record<string, unknown>
     return prototype === Object.prototype || prototype === null;
 }
 
-/** Checks whether value is a boolean primitive. */
+/** Returns true for boolean primitives (`true` or `false`). */
 export function isBoolean(value: unknown): value is boolean {
     return value === true || value === false;
 }
 
-/** Type guard checking whether string is included in allowed set. */
+/** Returns true when string belongs to allowed set. */
 export function isOneOf<T extends string>(value: unknown, allowed: readonly T[]): value is T {
     return typeof value === 'string' && (allowed as readonly string[]).includes(value);
 }

package/src/document.ts

@@ -4,7 +4,7 @@
 // biome-ignore-all lint/style/useNamingConvention: mirrors docling-core's snake_case JSON
 
 // -------------------------------------------------------------------
-// --- 1. Document
+// --- 1. Types
 // -------------------------------------------------------------------
 
 /**
@@ -54,9 +54,7 @@ export type PageItem = {
     page_no: number;
 };
 
-// -------------------------------------------------------------------
-// --- 2. Shared Parts
-// -------------------------------------------------------------------
+// Shared Parts
 
 /** JSON pointer to another item, e.g. `{ $ref: '#/texts/12' }` or `{ $ref: '#/body' }`. */
 export type RefItem = { $ref: string };
@@ -182,9 +180,7 @@ type FloatingFields = {
     image: ImageRef | null;
 };
 
-// -------------------------------------------------------------------
-// --- 3. Groups
-// -------------------------------------------------------------------
+// Groups
 
 /** Docling's group kinds. */
 export type GroupLabel =
@@ -214,9 +210,7 @@ export type ListGroup = GroupItem & { label: 'list' };
 /** Run of texts that belong to one line or paragraph, e.g. with mixed formatting. */
 export type InlineGroup = GroupItem & { label: 'inline' };
 
-// -------------------------------------------------------------------
-// --- 4. Texts
-// -------------------------------------------------------------------
+// Texts
 
 /** Labels of plain `TextItem`s; other text labels have their own item type. */
 export type TextLabel =
@@ -284,9 +278,7 @@ export type AnyTextItem =
     | FieldValueItem
     | TextItem;
 
-// -------------------------------------------------------------------
-// --- 5. Tables
-// -------------------------------------------------------------------
+// Tables
 
 /** Table cell; offsets are 0-based and end-exclusive, spans repeat the cell in `grid`. */
 export type TableCell = {
@@ -331,9 +323,7 @@ export type TableItem = DocItem &
         annotations: (DescriptionAnnotation | MiscAnnotation)[];
     };
 
-// -------------------------------------------------------------------
-// --- 6. Pictures
-// -------------------------------------------------------------------
+// Pictures
 
 /**
  * **Model output on a picture**: description, classification, molecule or chart data.
@@ -379,9 +369,7 @@ export type PictureItem = DocItem &
         annotations: PictureAnnotation[];
     };
 
-// -------------------------------------------------------------------
-// --- 7. Forms and Key-Value Regions
-// -------------------------------------------------------------------
+// Forms and Key-Value Regions
 
 /** Cell of a key-value or form graph. */
 export type GraphCell = {