extract-pdf 0.1.260 → 0.1.261

package/server/server.js

@@ -0,0 +1,180 @@
+/**
+ * @file server.js
+ * @description Entry point: wires middleware, route handlers, OpenAPI docs, and starts the server.
+ */
+import { serve } from "@hono/node-server";
+import { OpenAPIHono } from "@hono/zod-openapi";
+import { swaggerUI } from "@hono/swagger-ui";
+import { cors } from "hono/cors";
+import { logger } from "hono/logger";
+
+import { initializeModel, isModelLoaded, generateFromImage, load_image } from "./model.js";
+import { convertImageRoute, convertImageBase64Route, healthRoute } from "./routes.js";
+
+const app = new OpenAPIHono();
+
+app.use("*", cors());
+app.use("*", logger());
+
+/** Timestamp used to calculate uptime for the health endpoint. */
+const startTime = Date.now();
+
+// ── Health ────────────────────────────────────────────────────────────────────
+
+app.openapi(healthRoute, (c) =>
+    c.json({
+        status: "healthy",
+        modelLoaded: isModelLoaded(),
+        uptime: Date.now() - startTime,
+        version: "1.0.0",
+    })
+);
+
+// ── Convert (URL) ─────────────────────────────────────────────────────────────
+
+app.openapi(convertImageRoute, async (c) => {
+    const startProcessing = Date.now();
+
+    try {
+        const { imageUrl, prompt, maxTokens, streaming } = c.req.valid("json");
+
+        let image;
+        try {
+            image = await load_image(imageUrl);
+        } catch {
+            return c.json({ success: false, error: "Failed to load image from URL", code: "IMAGE_LOAD_ERROR" }, 400);
+        }
+
+        const { generatedText } = await generateFromImage({ image, prompt, maxTokens, streaming });
+
+        return c.json({
+            success: true,
+            result: generatedText,
+            metadata: { processingTime: Date.now() - startProcessing },
+        });
+    } catch (error) {
+        console.error("Conversion error:", error);
+        return c.json({ success: false, error: error.message || "Internal processing error", code: "PROCESSING_ERROR" }, 500);
+    }
+});
+
+// ── Convert (base64) ──────────────────────────────────────────────────────────
+
+app.openapi(convertImageBase64Route, async (c) => {
+    const startProcessing = Date.now();
+
+    try {
+        const { imageBase64, mimeType, prompt, maxTokens, streaming } = c.req.valid("json");
+
+        let image;
+        try {
+            image = await load_image(`data:${mimeType};base64,${imageBase64}`);
+        } catch {
+            return c.json({ success: false, error: "Failed to decode base64 image", code: "IMAGE_DECODE_ERROR" }, 400);
+        }
+
+        const { generatedText, generated_ids } = await generateFromImage({ image, prompt, maxTokens, streaming });
+
+        return c.json({
+            success: true,
+            result: generatedText,
+            metadata: {
+                processingTime: Date.now() - startProcessing,
+                tokenCount: generated_ids?.dims?.[1],
+            },
+        });
+    } catch (error) {
+        console.error("Conversion error:", error);
+        return c.json({ success: false, error: error.message || "Internal processing error", code: "PROCESSING_ERROR" }, 500);
+    }
+});
+
+// ── Streaming SSE endpoint ────────────────────────────────────────────────────
+
+/**
+ * POST /api/v1/convert-stream
+ * Streams generated tokens via Server-Sent Events.
+ * Not registered with OpenAPI because SSE responses fall outside the JSON schema.
+ */
+app.post("/api/v1/convert-stream", async (c) => {
+    const { imageUrl, prompt = "Convert this page to docling.", maxTokens = 4096 } = await c.req.json();
+
+    c.header("Content-Type", "text/event-stream");
+    c.header("Cache-Control", "no-cache");
+    c.header("Connection", "keep-alive");
+
+    const encoder = new TextEncoder();
+    const stream = new ReadableStream({
+        async start(controller) {
+            const send = (payload) =>
+                controller.enqueue(encoder.encode(`data: ${JSON.stringify(payload)}\n\n`));
+            try {
+                const { model, processor } = await initializeModel();
+                const image = await load_image(imageUrl);
+
+                const messages = [{
+                    role: "user",
+                    content: [{ type: "image" }, { type: "text", text: prompt }],
+                }];
+                const text = processor.apply_chat_template(messages, { add_generation_prompt: true });
+                const inputs = await processor(text, [image], { do_image_splitting: true });
+
+                let fullText = "";
+                const { TextStreamer } = await import("@huggingface/transformers");
+                const streamer = new TextStreamer(processor.tokenizer, {
+                    skip_prompt: true,
+                    skip_special_tokens: false,
+                    on_finalized_text: (chunk) => {
+                        fullText += chunk;
+                        send({ text: chunk, done: false });
+                    },
+                });
+
+                await model.generate({ ...inputs, max_new_tokens: maxTokens, streamer });
+                send({ text: "", done: true, fullText });
+            } catch (error) {
+                send({ error: error.message, done: true });
+            }
+            controller.close();
+        },
+    });
+
+    return new Response(stream);
+});
+
+// ── Docs & error handling ─────────────────────────────────────────────────────
+
+app.doc("/openapi.json", {
+    openapi: "3.0.0",
+    info: {
+        version: "1.0.0",
+        title: "Granite Docling API",
+        description: "API for converting images to docling format using the Granite Docling model",
+    },
+    servers: [{ url: "http://localhost:3000", description: "Development server" }],
+});
+
+app.get("/docs", swaggerUI({ url: "/openapi.json" }));
+app.get("/", (c) => c.redirect("/docs"));
+
+app.onError((err, c) => {
+    console.error(`${err}`);
+    return c.json({ success: false, error: err.message || "Internal server error", code: "INTERNAL_ERROR" }, 500);
+});
+
+app.notFound((c) =>
+    c.json({ success: false, error: "Endpoint not found", code: "NOT_FOUND" }, 404)
+);
+
+// ── Start ─────────────────────────────────────────────────────────────────────
+
+// Workers runtime uses the default export; Node.js uses serve().
+export default app;
+
+if (typeof process !== "undefined" && process.env.NODE_ENV !== "worker") {
+    initializeModel().catch(console.error);
+    const port = process.env.PORT || 3000;
+    console.log(`Server is running on port ${port}`);
+    console.log(`OpenAPI documentation available at http://localhost:${port}/docs`);
+    serve({ fetch: app.fetch, port });
+}

package/server/wrangler.jsonc

@@ -0,0 +1,18 @@
+{
+  "$schema": "node_modules/wrangler/config-schema.json",
+  "name": "pdf-to-html-docling",
+  "main": "server.js",
+  "compatibility_date": "2025-05-01",
+  // Required for Node.js built-ins (crypto, stream, path, etc.) used by
+  // @huggingface/transformers and @hono/node-server.
+  "compatibility_flags": ["nodejs_compat_v2"],
+  "dev": {
+    "port": 3000,
+    "local_protocol": "http"
+  },
+  // Workers free tier: 128 MB. Model inference is heavy — bump this when
+  // deploying to a paid account or Workers AI.
+  "limits": {
+    "cpu_ms": 30000
+  }
+}

package/src/docling-ocr.ts

@@ -0,0 +1,271 @@
+/**
+ * @fileoverview OCR of PDF pages with the Granite Docling vision model —
+ * either in-process (via the optional `@huggingface/transformers` dependency
+ * and the ONNX build of `ibm-granite/granite-docling-258M`) or by POSTing
+ * page images to a docling-compatible HTTP processor (the Hono service in
+ * this package's `server/` folder, or any other deployment of it).
+ *
+ * Everything heavy is imported lazily: requiring this module costs nothing
+ * until a page is actually OCR'd.
+ */
+
+/** Hugging Face id of the ONNX Granite Docling build used for local OCR. */
+const MODEL_ID = "onnx-community/granite-docling-258M-ONNX";
+
+/** Default instruction sent to the model per page. */
+const DEFAULT_PROMPT = "Convert this page to docling.";
+
+/** Options accepted by the docling OCR helpers. */
+export interface DoclingOcrOptions {
+  /**
+   * Base URL of a remote docling-compatible processor
+   * (e.g. `"http://localhost:3000"`). When set, page images are POSTed to
+   * `{processorUrl}/api/v1/convert-base64` instead of running the model
+   * in-process.
+   */
+  processorUrl?: string;
+  /** Instruction for the model. default="Convert this page to docling." */
+  prompt?: string;
+  /** Max tokens generated per page. default=4096 */
+  maxTokens?: number;
+  /** Rasterization scale for PDF pages (1 = 72 DPI). default=2 */
+  scale?: number;
+}
+
+// ── Local model (optional @huggingface/transformers) ─────────────────────────
+
+let localModelPromise: Promise<{ model: any; processor: any; lib: any }> | null =
+  null;
+
+/** Loads the Granite Docling ONNX model once and caches it. */
+async function loadLocalModel() {
+  if (!localModelPromise) {
+    localModelPromise = (async () => {
+      const lib = await import("@huggingface/transformers");
+      const processor = await lib.AutoProcessor.from_pretrained(MODEL_ID);
+      const model = await lib.AutoModelForVision2Seq.from_pretrained(MODEL_ID, {
+        dtype: "fp32",
+      });
+      return { model, processor, lib };
+    })();
+  }
+  return localModelPromise;
+}
+
+/**
+ * OCRs one image with Granite Docling and returns the raw doctags output.
+ * Uses the remote processor when `processorUrl` is set, otherwise the local
+ * ONNX model.
+ *
+ * @param imageBase64 - Base64-encoded PNG of the page/image (no data: prefix)
+ * @category Extract
+ */
+export async function ocrImageWithDocling(
+  imageBase64: string,
+  options: DoclingOcrOptions = {},
+): Promise<string> {
+  const {
+    processorUrl,
+    prompt = DEFAULT_PROMPT,
+    maxTokens = 4096,
+  } = options;
+
+  if (processorUrl) {
+    const response = await fetch(
+      `${processorUrl.replace(/\/$/, "")}/api/v1/convert-base64`,
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          imageBase64,
+          mimeType: "image/png",
+          prompt,
+          maxTokens,
+        }),
+      },
+    );
+    const data: any = await response.json();
+    if (!response.ok || !data?.success)
+      throw new Error(data?.error || `Processor error ${response.status}`);
+    return data.result;
+  }
+
+  const { model, processor, lib } = await loadLocalModel();
+  const image = await lib.load_image(`data:image/png;base64,${imageBase64}`);
+  const messages = [
+    {
+      role: "user",
+      content: [{ type: "image" }, { type: "text", text: prompt }],
+    },
+  ];
+  const text = processor.apply_chat_template(messages, {
+    add_generation_prompt: true,
+  });
+  const inputs = await processor(text, [image], { do_image_splitting: true });
+  const generated_ids = await model.generate({
+    ...inputs,
+    max_new_tokens: maxTokens,
+  });
+  const [decoded] = processor.batch_decode(
+    generated_ids.slice(null, [inputs.input_ids.dims.at(-1), null]),
+    { skip_special_tokens: true },
+  );
+  return decoded;
+}
+
+// ── Page rasterization ───────────────────────────────────────────────────────
+
+/** Creates a 2D canvas in whatever environment is available. */
+async function createCanvas(width: number, height: number): Promise<any> {
+  if (typeof document !== "undefined") {
+    const canvas = document.createElement("canvas");
+    canvas.width = width;
+    canvas.height = height;
+    return canvas;
+  }
+  try {
+    const napi: any = await import("@napi-rs/canvas" as any);
+    return napi.createCanvas(width, height);
+  } catch {
+    /* optional dependency not installed */
+  }
+  if (typeof OffscreenCanvas !== "undefined")
+    return new OffscreenCanvas(width, height);
+  throw new Error(
+    "No canvas available to rasterize PDF pages — install @napi-rs/canvas in Node.js, or run in a browser/Worker with OffscreenCanvas",
+  );
+}
+
+/** Encodes a canvas (DOM, Offscreen, or napi) as base64 PNG. */
+async function canvasToPngBase64(canvas: any): Promise<string> {
+  if (typeof canvas.toBuffer === "function")
+    return canvas.toBuffer("image/png").toString("base64");
+  if (typeof canvas.convertToBlob === "function") {
+    const blob = await canvas.convertToBlob({ type: "image/png" });
+    const bytes = new Uint8Array(await blob.arrayBuffer());
+    let binary = "";
+    for (const byte of bytes) binary += String.fromCharCode(byte);
+    return btoa(binary);
+  }
+  return canvas.toDataURL("image/png").split(",")[1];
+}
+
+/**
+ * Rasterizes one PDF.js page object to a base64 PNG.
+ * @param page - A page from `pdfDocument.getPage(n)`
+ * @category Extract
+ */
+export async function renderPdfPageToPngBase64(
+  page: any,
+  scale = 2,
+): Promise<string> {
+  const viewport = page.getViewport({ scale });
+  const canvas = await createCanvas(
+    Math.ceil(viewport.width),
+    Math.ceil(viewport.height),
+  );
+  const canvasContext = canvas.getContext("2d");
+  await page.render({ canvasContext, viewport }).promise;
+  return canvasToPngBase64(canvas);
+}
+
+/**
+ * OCRs a set of pages from a loaded PDF.js document with Granite Docling.
+ *
+ * @param pdfDocument - Document from PDF.js `getDocument(...).promise`
+ * @param pageNumbers - 1-based page numbers to OCR
+ * @returns Map of page number → HTML (converted from the model's doctags);
+ *   pages whose OCR failed are absent from the map.
+ * @category Extract
+ */
+export async function ocrPdfPagesWithDocling(
+  pdfDocument: any,
+  pageNumbers: number[],
+  options: DoclingOcrOptions = {},
+): Promise<Map<number, string>> {
+  const results = new Map<number, string>();
+  for (const pageNumber of pageNumbers) {
+    try {
+      const page = await pdfDocument.getPage(pageNumber);
+      const imageBase64 = await renderPdfPageToPngBase64(page, options.scale);
+      const doctags = await ocrImageWithDocling(imageBase64, options);
+      results.set(pageNumber, doctagsToHtml(doctags));
+    } catch (error) {
+      console.error(`Docling OCR failed for page ${pageNumber}:`, error);
+    }
+  }
+  return results;
+}
+
+// ── Doctags → HTML ───────────────────────────────────────────────────────────
+
+/** Converts an OTSL table body (`<fcel>a<fcel>b<nl>...`) to an HTML table. */
+function otslToHtmlTable(body: string): string {
+  const rows = body
+    .split("<nl>")
+    .map((row) => row.trim())
+    .filter(Boolean);
+  const html = rows
+    .map((row) => {
+      const cells = [...row.matchAll(/<(fcel|ched|rhed|ecel|lcel|ucel|xcel)>([^<]*)/g)];
+      if (!cells.length) return "";
+      const cellsHtml = cells
+        .map(([, kind, content]) => {
+          const tag = kind === "ched" || kind === "rhed" ? "th" : "td";
+          return `<${tag}>${content.trim()}</${tag}>`;
+        })
+        .join("");
+      return `<tr>${cellsHtml}</tr>`;
+    })
+    .filter(Boolean)
+    .join("");
+  return `<table>${html}</table>`;
+}
+
+/**
+ * Converts Granite Docling's doctags output to plain HTML: strips location
+ * tokens, maps doctags elements (section headers, text, lists, code,
+ * formulas, captions, OTSL tables) to their HTML equivalents, and drops page
+ * furniture (running headers/footers). Best-effort — unknown tags are
+ * removed, their text content kept.
+ * @category Extract
+ */
+export function doctagsToHtml(doctags: string): string {
+  let html = (doctags || "")
+    // location / special tokens
+    .replace(/<\/?doctag>/g, "")
+    .replace(/<loc_\d+>/g, "")
+    .replace(/<page_break>/g, "")
+    .replace(/<end_of_utterance>/g, "")
+    // page furniture carries no content value
+    .replace(/<page_(?:header|footer)>[\s\S]*?<\/page_(?:header|footer)>/g, "");
+
+  // OTSL tables
+  html = html.replace(/<otsl>([\s\S]*?)<\/otsl>/g, (_, body) =>
+    otslToHtmlTable(body),
+  );
+
+  const tagMap: Array<[RegExp, string, string]> = [
+    [/<title>([\s\S]*?)<\/title>/g, "<h1>", "</h1>"],
+    [/<section_header_level_1>([\s\S]*?)<\/section_header_level_1>/g, "<h2>", "</h2>"],
+    [/<section_header_level_2>([\s\S]*?)<\/section_header_level_2>/g, "<h3>", "</h3>"],
+    [/<section_header_level_3>([\s\S]*?)<\/section_header_level_3>/g, "<h4>", "</h4>"],
+    [/<section_header_level_[4-9]>([\s\S]*?)<\/section_header_level_[4-9]>/g, "<h5>", "</h5>"],
+    [/<(?:text|paragraph)>([\s\S]*?)<\/(?:text|paragraph)>/g, "<p>", "</p>"],
+    [/<caption>([\s\S]*?)<\/caption>/g, "<figcaption>", "</figcaption>"],
+    [/<(?:picture|chart)>([\s\S]*?)<\/(?:picture|chart)>/g, "<figure>", "</figure>"],
+    [/<code>([\s\S]*?)<\/code>/g, "<pre><code>", "</code></pre>"],
+    [/<formula>([\s\S]*?)<\/formula>/g, '<code class="formula">', "</code>"],
+    [/<footnote>([\s\S]*?)<\/footnote>/g, '<p class="footnote">', "</p>"],
+    [/<list_item>([\s\S]*?)<\/list_item>/g, "<li>", "</li>"],
+    [/<unordered_list>([\s\S]*?)<\/unordered_list>/g, "<ul>", "</ul>"],
+    [/<ordered_list>([\s\S]*?)<\/ordered_list>/g, "<ol>", "</ol>"],
+  ];
+  for (const [regex, open, close] of tagMap)
+    html = html.replace(regex, (_, content) => `${open}${content.trim()}${close}`);
+
+  // Drop any leftover doctags-style tokens, keeping their inner text.
+  html = html.replace(/<\/?(?:[a-z][a-z0-9]*_[a-z0-9_]+|otsl|smiles)>/g, "");
+
+  return html.trim();
+}

package/src/ocr-page-scan.ts

@@ -0,0 +1,141 @@
+/**
+ * @fileoverview Dependency-free, regex-based scan of per-page PDF text that
+ * flags which pages contain infographics, figures, charts, or tables — the
+ * pages worth sending through a heavy OCR model (e.g. Granite Docling) instead
+ * of the fast text-layer pipeline. Complements `detectPdfNeedsOcr` (which uses
+ * LiteParse's native complexity analysis and is Node.js only): this scan runs
+ * anywhere on plain strings, so it also powers the `"hybrid"` processor mode
+ * of {@link convertPDFToHTML}.
+ */
+
+/**
+ * Captions and labels that indicate a figure/table/graphic on the page,
+ * e.g. "Figure 3", "Fig. 2:", "Table IV", "Chart 1", "Infographic 2".
+ */
+const CAPTION_REGEX =
+  /\b(?:fig(?:ure)?s?|table|chart|graph|diagram|infographic|exhibit|illustration|plate|scheme)\s*\.?\s*(?:\d+(?:\.\d+)*|[ivxlcdm]+)\b/gi;
+
+/**
+ * A line that reads like a table row: 3+ cells separated by tabs or runs of
+ * 2+ spaces (column-aligned text layers keep those gaps).
+ */
+const TABLE_ROW_REGEX = /^\s*\S[^\t\n]{0,60}?(?:\t+| {2,})\S[^\t\n]{0,60}?(?:\t+| {2,})\S/;
+
+/**
+ * A run of 3+ numeric cells (optionally with %, $, commas) in a row — data
+ * tables and chart axis labels produce these even without column gaps.
+ */
+const NUMERIC_ROW_REGEX = /(?:[-+]?[\d][\d.,]*\s*[%$€£]?\s+){3,}[-+]?[\d]/;
+
+/** Characters that show up when a text layer is garbled/unmapped glyphs. */
+const GARBLED_REGEX = /[\uFFFD\u0000-\u0008\u000B\u000C\u000E-\u001F]/g;
+
+/** Per-page result of {@link scanPagesForOCR}. */
+export interface PageOcrScan {
+  /** 1-based page number. */
+  page: number;
+  /** True when the page should be routed through OCR. */
+  needsOcr: boolean;
+  /**
+   * Why the page was flagged: `"no-text"`, `"sparse-text"`, `"garbled-text"`,
+   * `"figure-caption"`, `"table-caption"`, `"table-rows"`, `"numeric-grid"`.
+   * Empty when `needsOcr` is false.
+   */
+  reasons: string[];
+  /** Caption strings matched on the page (e.g. `"Figure 3"`, `"Table 2"`). */
+  captions: string[];
+}
+
+/** Result of {@link scanPagesForOCR}. */
+export interface OcrScanResult {
+  /** True when any page was flagged. */
+  needsOcr: boolean;
+  /** 1-based page numbers of every flagged page. */
+  pagesNeedingOcr: number[];
+  /** Per-page detail, one entry per page in input order. */
+  pages: PageOcrScan[];
+}
+
+/** Options for {@link scanPagesForOCR}. */
+export interface ScanPagesForOCROptions {
+  /**
+   * Pages with fewer non-whitespace characters than this are flagged as
+   * `"sparse-text"` (likely a scanned image or a full-page graphic).
+   * default=200
+   */
+  sparseTextThreshold?: number;
+  /** Minimum table-looking lines before flagging `"table-rows"`. default=3 */
+  minTableRows?: number;
+  /** Minimum numeric-run lines before flagging `"numeric-grid"`. default=2 */
+  minNumericRows?: number;
+}
+
+/**
+ * Scans per-page extracted text with regex heuristics and reports which pages
+ * contain infographics/figures/tables (or have no usable text layer) and
+ * therefore need to be OCR'd for full fidelity.
+ *
+ * @param pageTexts - Extracted plain text of each page, in page order
+ * @param options - Threshold tuning, see {@link ScanPagesForOCROptions}
+ * @category Extract
+ */
+export function scanPagesForOCR(
+  pageTexts: string[],
+  options: ScanPagesForOCROptions = {},
+): OcrScanResult {
+  const {
+    sparseTextThreshold = 200,
+    minTableRows = 3,
+    minNumericRows = 2,
+  } = options;
+
+  const pages: PageOcrScan[] = pageTexts.map((text, index) => {
+    const reasons: string[] = [];
+    const compact = (text || "").replace(/\s+/g, " ").trim();
+
+    // Text-layer health: nothing/near-nothing extractable means the page is
+    // an image (scan or full-page infographic) as far as pdfjs is concerned.
+    if (compact.length === 0) reasons.push("no-text");
+    else if (compact.length < sparseTextThreshold) reasons.push("sparse-text");
+
+    const garbled = (text || "").match(GARBLED_REGEX)?.length || 0;
+    if (compact.length > 0 && garbled / compact.length > 0.05)
+      reasons.push("garbled-text");
+
+    // Captions referencing figures/charts vs tables. Only line-leading
+    // matches count as flags — a real caption starts its own line, while
+    // prose like "see Figure 1" does not mean the figure is on this page.
+    const captions = [...(text || "").matchAll(CAPTION_REGEX)].map((m) =>
+      m[0].replace(/\s+/g, " ").trim(),
+    );
+    const leadingCaptions = [
+      ...(text || "").matchAll(new RegExp(`^\\s*${CAPTION_REGEX.source}`, "gim")),
+    ].map((m) => m[0].trim());
+    if (leadingCaptions.some((c) => /^table/i.test(c)))
+      reasons.push("table-caption");
+    if (leadingCaptions.some((c) => !/^table/i.test(c)))
+      reasons.push("figure-caption");
+
+    // Column-aligned or numeric rows.
+    const lines = (text || "").split(/\r?\n/);
+    const tableRows = lines.filter((line) => TABLE_ROW_REGEX.test(line)).length;
+    const numericRows = lines.filter((line) =>
+      NUMERIC_ROW_REGEX.test(line),
+    ).length;
+    if (tableRows >= minTableRows) reasons.push("table-rows");
+    if (numericRows >= minNumericRows) reasons.push("numeric-grid");
+
+    return {
+      page: index + 1,
+      needsOcr: reasons.length > 0,
+      reasons,
+      captions,
+    };
+  });
+
+  const pagesNeedingOcr = pages
+    .filter((page) => page.needsOcr)
+    .map((page) => page.page);
+
+  return { needsOcr: pagesNeedingOcr.length > 0, pagesNeedingOcr, pages };
+}