docling-serve-client 0.4.0 → 0.6.0

package/dist/index.js

@@ -250,6 +250,70 @@ function fail(error) {
   return { ok: false, error };
 }
 
+// src/capabilities.ts
+function readCapabilities(body) {
+  if (!isPlainObject(body)) {
+    return fail(ERR.INVALID_RESPONSE("Capabilities response is not a JSON object"));
+  }
+  const targets = objectOf(body.targets);
+  const features = objectOf(body.features);
+  return ok({
+    versions: Object.fromEntries(Object.entries(objectOf(body.versions)).filter((entry) => typeof entry[1] === "string")),
+    stages: Object.fromEntries(Object.entries(objectOf(body.stages)).map(([name, stage]) => [name, readStage(objectOf(stage))])),
+    sources: stringsOf(body.sources),
+    targets: { allowed: stringsOf(targets.allowed), default: stringOf(targets.default) },
+    outputFormats: stringsOf(body.output_formats),
+    imageExportModes: stringsOf(body.image_export_modes),
+    limits: readLimits(objectOf(body.limits)),
+    features: {
+      apiKeyRequired: features.api_key_required === true,
+      artifactStorage: features.artifact_storage === true,
+      websocket: features.websocket === true
+    }
+  });
+}
+function readStage(stage) {
+  const presets = [];
+  for (const item of Array.isArray(stage.presets) ? stage.presets : []) {
+    const preset = objectOf(item);
+    if (typeof preset.id === "string") {
+      presets.push({
+        id: preset.id,
+        name: stringOf(preset.name),
+        description: typeof preset.description === "string" ? preset.description : null,
+        source: stringOf(preset.source)
+      });
+    }
+  }
+  return {
+    option: stringOf(stage.option),
+    customConfigOption: typeof stage.custom_config_option === "string" ? stage.custom_config_option : null,
+    default: stringOf(stage.default),
+    presets
+  };
+}
+function readLimits(limits) {
+  return {
+    maxDocumentTimeout: numberOf(limits.max_document_timeout),
+    maxImagesScale: numberOf(limits.max_images_scale),
+    maxSourcesPerRequest: numberOf(limits.max_sources_per_request),
+    maxNumPages: numberOf(limits.max_num_pages),
+    maxFileSize: numberOf(limits.max_file_size)
+  };
+}
+function objectOf(value) {
+  return isPlainObject(value) ? value : {};
+}
+function stringsOf(value) {
+  return Array.isArray(value) ? value.filter((item) => typeof item === "string") : [];
+}
+function stringOf(value) {
+  return typeof value === "string" ? value : "";
+}
+function numberOf(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+
 // src/core/http.ts
 var STRING_TOO_LONG = "ERR_STRING_TOO_LONG";
 var MATCH_OUT_OF_MEMORY = /out of memory/i;
@@ -368,7 +432,8 @@ var DEFAULT_OPTIONS = Object.freeze({
   pipeline: "standard",
   pdfBackend: "docling_parse",
   ocr: true,
-  forceOcr: false
+  forceOcr: false,
+  ocrEngine: "auto"
 });
 var CALL_OPTION_RULES = {
   headingHierarchy: isBoolean,
@@ -378,7 +443,8 @@ var CALL_OPTION_RULES = {
   pipeline: (value) => isOneOf(value, PIPELINES),
   pdfBackend: (value) => isOneOf(value, PDF_BACKENDS),
   ocr: isBoolean,
-  forceOcr: isBoolean
+  forceOcr: isBoolean,
+  ocrEngine: (value) => typeof value === "string" && value !== ""
 };
 var CLIENT_OPTION_RULES = {
   ...CALL_OPTION_RULES,
@@ -405,24 +471,46 @@ var IMAGE_OPTION_RULES = {
 var CHECK_RULES = {
   signal: isAbortSignal
 };
+var POLL_RULES = {
+  ...CHECK_RULES,
+  pollMs: isTimerDelay
+};
+var RUN_MARKDOWN_RULES = {
+  ...MARKDOWN_RULES,
+  ...POLL_RULES
+};
+var RUN_DOCUMENT_RULES = {
+  ...DOCUMENT_RULES,
+  ...POLL_RULES
+};
 var CONFIG_RULES = {
   baseUrl: isHttpUrl,
   apiKey: (value) => typeof value === "string" && value !== "",
   fetch: (value) => typeof value === "function",
-  timeoutMs: isPositiveNumber,
+  timeoutMs: isTimerDelay,
+  pollMs: isTimerDelay,
   options: isPlainObject
 };
+var DEFAULT_POLL_MS = 10;
 var MATCH_JOB_ID = /^[\w-]+$/;
 var MATCH_LANGUAGE_TAG = /^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8})*$/;
 var MATCH_IMAGE_PREFIX = /^[^\s()<>]+$/;
 var MATCH_TRAILING_SLASHES = /\/+$/;
 var MATCH_HTTP_PROTOCOL = /^https?:$/;
+var MAX_TIMEOUT_MS = 2147483647;
 var INVALID_JOB = "Expected the job object returned by submitMarkdown() or submitDocument()";
 function resolveConfig(config) {
   if (!isPlainObject(config)) {
     throw new TypeError("Invalid config: expected an object");
   }
-  const { baseUrl, apiKey, fetch: fetchFn, timeoutMs, options } = validateKeys(config, CONFIG_RULES);
+  const {
+    baseUrl,
+    apiKey,
+    fetch: fetchFn,
+    timeoutMs,
+    pollMs = DEFAULT_POLL_MS,
+    options
+  } = validateKeys(config, CONFIG_RULES);
   if (baseUrl === undefined) {
     throw new TypeError(invalidValue("baseUrl"));
   }
@@ -435,31 +523,31 @@ function resolveConfig(config) {
     ...apiKey === undefined ? {} : { apiKey },
     fetch: fetchFn ?? fetch,
     ...timeoutMs === undefined ? {} : { timeoutMs },
+    pollMs,
     defaults
   };
 }
 function resolveMarkdownCall(defaults, options) {
-  const {
-    signal,
-    images = "placeholder",
-    imageOptions,
-    ...docling
-  } = validateKeys(callObject(options), MARKDOWN_RULES);
-  const output = resolveImageOutput(images, imageOptions);
-  return { options: { ...defaults, ...docling }, output, ...signal === undefined ? {} : { signal } };
+  return toMarkdownCall(defaults, validateKeys(callObject(options), MARKDOWN_RULES));
 }
 function resolveDocumentCall(defaults, options) {
-  const {
-    signal,
-    images = "embedded",
-    pageImages = false,
-    ...docling
-  } = validateKeys(callObject(options), DOCUMENT_RULES);
-  return { options: { ...defaults, ...docling }, images, pageImages, ...signal === undefined ? {} : { signal } };
+  return toDocumentCall(defaults, validateKeys(callObject(options), DOCUMENT_RULES));
+}
+function resolveRunMarkdownCall(defaults, defaultPollMs, options) {
+  const { pollMs = defaultPollMs, ...call } = validateKeys(callObject(options), RUN_MARKDOWN_RULES);
+  return { ...toMarkdownCall(defaults, call), pollMs };
+}
+function resolveRunDocumentCall(defaults, defaultPollMs, options) {
+  const { pollMs = defaultPollMs, ...call } = validateKeys(callObject(options), RUN_DOCUMENT_RULES);
+  return { ...toDocumentCall(defaults, call), pollMs };
 }
 function resolveCheckOptions(options) {
   return validateKeys(callObject(options), CHECK_RULES);
 }
+function resolvePollOptions(defaultPollMs, options) {
+  const { pollMs = defaultPollMs, signal } = validateKeys(callObject(options), POLL_RULES);
+  return { pollMs, ...signal === undefined ? {} : { signal } };
+}
 function validateJob(job) {
   if (!isPlainObject(job) || !isJobId(job.id)) {
     return fail(ERR.INVALID_INPUT(INVALID_JOB));
@@ -492,6 +580,15 @@ function callObject(options) {
   }
   return options;
 }
+function toMarkdownCall(defaults, options) {
+  const { signal, images = "placeholder", imageOptions, ...docling } = options;
+  const output = resolveImageOutput(images, imageOptions);
+  return { options: { ...defaults, ...docling }, output, ...signal === undefined ? {} : { signal } };
+}
+function toDocumentCall(defaults, options) {
+  const { signal, images = "embedded", pageImages = false, ...docling } = options;
+  return { options: { ...defaults, ...docling }, images, pageImages, ...signal === undefined ? {} : { signal } };
+}
 function resolveImageOutput(images, imageOptions) {
   if (images !== "extract") {
     if (imageOptions !== undefined) {
@@ -514,6 +611,9 @@ function resolveImageOutput(images, imageOptions) {
 function isPositiveNumber(value) {
   return typeof value === "number" && Number.isFinite(value) && value > 0;
 }
+function isTimerDelay(value) {
+  return typeof value === "number" && Number.isInteger(value) && value >= 1 && value <= MAX_TIMEOUT_MS;
+}
 function isPageRange(value) {
   return Array.isArray(value) && value.length === 2 && Number.isInteger(value[0]) && Number.isInteger(value[1]) && value[0] >= 1 && value[1] >= value[0];
 }
@@ -527,7 +627,11 @@ function isAbortSignal(value) {
   return value instanceof AbortSignal;
 }
 function isHttpUrl(value) {
-  return typeof value === "string" && URL.canParse(value) && MATCH_HTTP_PROTOCOL.test(new URL(value).protocol);
+  if (typeof value !== "string" || !URL.canParse(value) || value.includes("?") || value.includes("#")) {
+    return false;
+  }
+  const url = new URL(value);
+  return MATCH_HTTP_PROTOCOL.test(url.protocol) && url.username === "" && url.password === "";
 }
 
 // src/response.ts
@@ -635,10 +739,11 @@ function isPageNumber(value) {
 }
 
 // src/client.ts
-var FIXED_FORM_FIELDS = [
-  ["do_table_structure", "true"],
-  ["table_mode", "accurate"]
-];
+var TABLE_STRUCTURE_PRESET = "tableformer_v1_accurate";
+var VLM_PIPELINE_PRESET = "granite_docling";
+var CHART_EXTRACTION_PRESET = "granite_vision_v4";
+var CODE_FORMULA_PRESET = "codeformulav2";
+var MATCH_UPPER_CASE = /[A-Z]/g;
 var INVALID_INPUT = "Expected a non-empty PDF, PNG, JPEG, TIFF or WebP as Uint8Array";
 var SERVER_ANSWERED = new Set([
   "http",
@@ -649,7 +754,7 @@ var SERVER_ANSWERED = new Set([
 var VERSION_TIMEOUT_MS = 2000;
 var MAX_SHOWN_ID_LENGTH = 100;
 function createDoclingClient(config) {
-  const { baseUrl, apiKey, fetch: fetchFn, timeoutMs, defaults } = resolveConfig(config);
+  const { baseUrl, apiKey, fetch: fetchFn, timeoutMs, pollMs, defaults } = resolveConfig(config);
   const headers = apiKey === undefined ? {} : { "X-Api-Key": apiKey };
   let versionsCache;
   return {
@@ -657,13 +762,21 @@ function createDoclingClient(config) {
     convertDocument,
     submitMarkdown,
     submitDocument,
-    check
+    check,
+    runMarkdown,
+    runDocument,
+    waitForJob,
+    capabilities
   };
   async function convertMarkdown(input, options) {
     const call = resolveMarkdownCall(defaults, options);
     const fields = { 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(readMarkdown(res.data.body, call.output));
+    return converted.ok ? ok({ ...converted.data, settings: res.data.settings }) : converted;
   }
   async function convertDocument(input, options) {
     const call = resolveDocumentCall(defaults, options);
@@ -673,31 +786,79 @@ function createDoclingClient(config) {
       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(readDocument(res.data.body));
+    return converted.ok ? ok({ ...converted.data, settings: res.data.settings }) : converted;
   }
   async function submitMarkdown(input, options) {
     const call = resolveMarkdownCall(defaults, options);
-    const fields = { 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);
   }
   async function submitDocument(input, options) {
     const call = resolveDocumentCall(defaults, options);
+    return await startDocumentJob(input, call);
+  }
+  async function runMarkdown(input, options) {
+    const call = resolveRunMarkdownCall(defaults, pollMs, options);
+    const job = await startMarkdownJob(input, call);
+    if (!job.ok) {
+      return job;
+    }
+    const done = await pollUntilDone(job.data, call);
+    return done.ok ? ok({ ...done.data, settings: job.data.settings }) : done;
+  }
+  async function runDocument(input, options) {
+    const call = resolveRunDocumentCall(defaults, pollMs, options);
+    const job = await startDocumentJob(input, call);
+    if (!job.ok) {
+      return job;
+    }
+    const done = await pollUntilDone(job.data, call);
+    return done.ok ? ok({ ...done.data, settings: job.data.settings }) : done;
+  }
+  async function waitForJob(job, options) {
+    const call = resolvePollOptions(pollMs, options);
+    const valid = validateJob(job);
+    return valid.ok ? pollUntilDone(valid.data, call) : valid;
+  }
+  async function startMarkdownJob(input, call) {
+    const fields = { 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;
+  }
+  async function startDocumentJob(input, call) {
     const fields = {
       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;
+  }
+  async function pollUntilDone(job, { pollMs: waitMs, signal }) {
+    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);
+      }
+      if (!await sleep(waitMs, signal)) {
+        return fail(ERR.ABORTED(`Aborted while waiting for job ${job.id}`));
+      }
+    }
   }
   async function check(job, options) {
     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;
+  }
+  async function fetchJobState(job, signal) {
+    const { id } = job;
     const res = await get(`/v1/status/poll/${id}`, signal);
     if (!res.ok) {
       const error = res.error.status === 404 ? ERR.NOT_FOUND(`Unknown job id: ${id} (${res.error.message})`) : res.error;
@@ -718,8 +879,7 @@ function createDoclingClient(config) {
           const error = result.error.status === 404 ? ERR.NOT_FOUND(`Result already fetched or expired: ${id}; resubmit the PDF (${result.error.message})`) : result.error;
           return failWithVersions(error);
         }
-        const checked = valid.data;
-        const output = checked.kind === "markdown" ? readMarkdown(result.data, checked.output) : readDocument(result.data);
+        const output = job.kind === "markdown" ? readMarkdown(result.data, job.output) : readDocument(result.data);
         const done = await withVersions(output);
         return done.ok ? ok({ status: "done", ...done.data }) : done;
       }
@@ -733,12 +893,21 @@ function createDoclingClient(config) {
         return failWithVersions(ERR.INVALID_RESPONSE(`Unexpected task status: ${String(task.task_status)}`));
     }
   }
+  async function capabilities(options) {
+    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);
+  }
   async function submit(input, options, fields, signal) {
     const res = await post("/v1/convert/file/async", input, options, fields, signal);
     if (!res.ok) {
       return res;
     }
-    const id = res.data?.task_id;
+    const id = res.data.body?.task_id;
     if (readText(id) === undefined) {
       return failWithVersions(ERR.INVALID_RESPONSE("Response has no task_id"));
     }
@@ -746,16 +915,17 @@ function createDoclingClient(config) {
       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 });
   }
   async function post(route, input, options, fields, signal) {
     const format = readInputFormat(input);
     if (!format.ok) {
       return format;
     }
+    const settings = buildSettings(format.data, options, fields);
     let body;
     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)}`));
     }
@@ -766,7 +936,7 @@ function createDoclingClient(config) {
       body,
       ...limited === undefined ? {} : { signal: limited }
     });
-    return res.ok ? res : failWithVersions(res.error);
+    return res.ok ? ok({ body: res.data, settings }) : failWithVersions(res.error);
   }
   function get(route, signal, limit = true) {
     const limited = limit ? withTimeout(signal, timeoutMs) : signal;
@@ -806,6 +976,22 @@ function createDoclingClient(config) {
     return versions.length === 0 ? null : Object.fromEntries(versions);
   }
 }
+function sleep(ms, signal) {
+  if (signal?.aborted) {
+    return Promise.resolve(false);
+  }
+  return new Promise((resolve) => {
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve(true);
+    }, ms);
+    function onAbort() {
+      clearTimeout(timer);
+      resolve(false);
+    }
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
 function withTimeout(signal, timeoutMs) {
   if (timeoutMs === undefined) {
     return signal;
@@ -822,43 +1008,51 @@ function readInputFormat(input) {
   const offset = format.fromFormat === "pdf" ? findTruncatedXref(bytes) : undefined;
   return offset === undefined ? ok(format) : fail(ERR.INVALID_INPUT(`PDF is truncated: cross-reference offset ${offset} lies past the end of the file (${bytes.length} bytes)`));
 }
-function buildFormData(input, { fromFormat, mimeType, fileName }, options, { format, embedImages, pageImages }) {
+function buildSettings({ fromFormat }, options, { format, embedImages, pageImages }) {
+  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
+  };
+}
+function buildFormData(input, { mimeType, fileName }, settings) {
   const form = new FormData;
   const bytes = input.buffer instanceof ArrayBuffer ? input : 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);
-  const isImage = fromFormat === "image";
-  form.append("do_ocr", String(isImage || options.ocr));
-  form.append("force_ocr", String(!isImage && options.forceOcr));
-  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;
 }
@@ -870,5 +1064,5 @@ export {
   toPageImageBox
 };
 
-//# debugId=B34739AC554F7F9C64756E2164756E21
+//# debugId=1022B5E8A749497A64756E2164756E21
 //# sourceMappingURL=index.js.map