@heripo/pdf-parser 0.1.30 → 0.1.31

package/dist/index.js

@@ -1,6 +1,6 @@
 // src/core/pdf-parser.ts
 import { Docling } from "docling-sdk";
-import { join as join16 } from "path";
+import { join as join17 } from "path";
 
 // src/config/constants.ts
 var PDF_PARSER = {
@@ -44,7 +44,7 @@ var DOCLING_ENVIRONMENT = {
 var PAGE_RENDERING = {
   /** Default rendering DPI for VLM text recognition quality */
   DEFAULT_DPI: 200,
-  /** Low-resolution DPI for OCR strategy sampling */
+  /** Low-resolution DPI for language detection sampling */
   SAMPLE_DPI: 150
 };
 var CHUNKED_CONVERSION = {
@@ -981,17 +981,14 @@ function checkMacOSVersion() {
   }
 }
 
-// src/errors/image-pdf-fallback-error.ts
-var ImagePdfFallbackError = class extends Error {
-  constructor(originalError, fallbackError) {
-    super(
-      `PDF conversion failed with fallback. Original: ${originalError.message}. Fallback: ${fallbackError.message}`
-    );
-    this.originalError = originalError;
-    this.fallbackError = fallbackError;
-  }
-  name = "ImagePdfFallbackError";
-};
+// src/core/pdf-converter.ts
+import { existsSync as existsSync10, rmSync as rmSync7 } from "fs";
+import { join as join16 } from "path";
+
+// src/detectors/pdf-language-detector.ts
+import { normalizeToBcp47 } from "@heripo/model";
+import { readFileSync } from "fs";
+import { z } from "zod/v4";
 
 // src/processors/pdf-text-extractor.ts
 var PdfTextExtractor = class _PdfTextExtractor {
@@ -1122,8 +1119,376 @@ var PdfTextExtractor = class _PdfTextExtractor {
   }
 };
 
+// src/prompts/korean-document-detection-prompt.ts
+var KOREAN_DOCUMENT_DETECTION_PROMPT = `Look at this page image carefully and identify all languages present on this page.
+
+Return an array of ocrmac-compatible language tags ordered by prevalence (primary language first).
+Use ko-KR when Korean text is present, even when the page also contains Hanja (\u6F22\u5B57/Chinese characters), English, numbers, tables, or captions.
+
+Supported tags: ar-SA, ars-SA, cs-CZ, da-DK, de-DE, en-US, es-ES, fr-FR, id-ID, it-IT, ja-JP, ko-KR, ms-MY, nb-NO, nl-NL, nn-NO, no-NO, pl-PL, pt-BR, ro-RO, ru-RU, sv-SE, th-TH, tr-TR, uk-UA, vi-VT, yue-Hans, yue-Hant, zh-Hans, zh-Hant.
+Examples: ["ko-KR", "en-US"], ["ja-JP"], ["zh-Hant", "en-US"]`;
+
+// src/detectors/pdf-language-detector.ts
+var DEFAULT_MAX_SAMPLE_PAGES = 15;
+var DEFAULT_MAX_RETRIES = 3;
+var EDGE_TRIM_RATIO = 0.1;
+var HANGUL_REGEX = /[\u1100-\u11ff\u3130-\u318f\uac00-\ud7af]/g;
+var JAPANESE_KANA_REGEX = /[\u3040-\u30ff]/g;
+var LATIN_REGEX = /[A-Za-z]/g;
+var DEFAULT_OCR_LANGUAGES = ["ko-KR", "en-US"];
+var languageDetectionSchema = z.object({
+  detectedLanguages: z.array(z.string()).describe(
+    "BCP 47 language tags found on this page, ordered by prevalence."
+  )
+});
+var PdfLanguageDetector = class {
+  constructor(logger, pageRenderer, textExtractor) {
+    this.logger = logger;
+    this.pageRenderer = pageRenderer;
+    this.textExtractor = textExtractor ?? new PdfTextExtractor(logger);
+  }
+  textExtractor;
+  async detect(pdfPath, outputDir, options) {
+    this.logger.info(
+      "[PdfLanguageDetector] Starting PDF language detection..."
+    );
+    const textLayerResult = await this.detectFromTextLayer(pdfPath);
+    if (textLayerResult) {
+      return textLayerResult;
+    }
+    if (!options?.model) {
+      this.logger.info(
+        `[PdfLanguageDetector] Language detection model not configured; using default OCR languages: ${JSON.stringify(DEFAULT_OCR_LANGUAGES)}`
+      );
+      return {
+        detectedLanguages: [...DEFAULT_OCR_LANGUAGES],
+        reason: "Language detection model not configured",
+        sampledPages: 0,
+        totalPages: 0,
+        source: "default"
+      };
+    }
+    return this.detectFromSampledPages(pdfPath, outputDir, {
+      ...options,
+      model: options.model
+    });
+  }
+  async detectFromTextLayer(pdfPath) {
+    try {
+      const totalPages = await this.textExtractor.getPageCount(pdfPath);
+      if (totalPages === 0) return null;
+      const fullText = await this.textExtractor.extractFullText(pdfPath);
+      if (fullText.trim().length === 0) {
+        this.logger.debug(
+          "[PdfLanguageDetector] No text in text layer; falling back to sampled language detection"
+        );
+        return null;
+      }
+      const detectedLanguages = this.detectLanguagesFromText(fullText);
+      if (detectedLanguages.length === 0) {
+        this.logger.debug(
+          "[PdfLanguageDetector] No known language signal in text layer; falling back to sampled language detection"
+        );
+        return null;
+      }
+      this.logger.info(
+        `[PdfLanguageDetector] Languages detected in text layer: ${detectedLanguages.join(", ")}`
+      );
+      return {
+        detectedLanguages,
+        reason: `Languages found in PDF text layer (${totalPages} pages checked)`,
+        sampledPages: totalPages,
+        totalPages,
+        source: "text-layer"
+      };
+    } catch {
+      this.logger.debug(
+        "[PdfLanguageDetector] Text layer language detection failed; falling back to sampled language detection"
+      );
+      return null;
+    }
+  }
+  detectLanguagesFromText(text) {
+    const scores = [
+      { tag: "ko-KR", count: this.countMatches(text, HANGUL_REGEX) },
+      { tag: "ja-JP", count: this.countMatches(text, JAPANESE_KANA_REGEX) },
+      { tag: "en-US", count: this.countMatches(text, LATIN_REGEX) }
+    ];
+    return scores.filter(({ count }) => count > 0).sort((a, b) => b.count - a.count).map(({ tag }) => tag);
+  }
+  countMatches(text, regex) {
+    regex.lastIndex = 0;
+    return text.match(regex)?.length ?? 0;
+  }
+  async detectFromSampledPages(pdfPath, outputDir, options) {
+    const renderResult = await this.pageRenderer.renderPages(
+      pdfPath,
+      outputDir,
+      {
+        dpi: PAGE_RENDERING.SAMPLE_DPI
+      }
+    );
+    if (renderResult.pageCount === 0) {
+      this.logger.info(
+        `[PdfLanguageDetector] No pages found; using default OCR languages: ${JSON.stringify(DEFAULT_OCR_LANGUAGES)}`
+      );
+      return {
+        detectedLanguages: [...DEFAULT_OCR_LANGUAGES],
+        reason: "No pages found in PDF",
+        sampledPages: 0,
+        totalPages: 0,
+        source: "default"
+      };
+    }
+    const sampleIndices = this.selectSamplePages(
+      renderResult.pageCount,
+      options.maxSamplePages ?? DEFAULT_MAX_SAMPLE_PAGES
+    );
+    this.logger.info(
+      `[PdfLanguageDetector] Sampling ${sampleIndices.length} of ${renderResult.pageCount} pages for language detection: [${sampleIndices.map((i) => i + 1).join(", ")}]`
+    );
+    const languageFrequency = /* @__PURE__ */ new Map();
+    let sampledPages = 0;
+    for (const index of sampleIndices) {
+      const pageFile = renderResult.pageFiles[index];
+      if (!pageFile) continue;
+      sampledPages += 1;
+      const detectedLanguages2 = await this.analyzeSamplePage(
+        pageFile,
+        index + 1,
+        options
+      );
+      for (const language of detectedLanguages2) {
+        languageFrequency.set(
+          language,
+          (languageFrequency.get(language) ?? 0) + 1
+        );
+      }
+    }
+    const detectedLanguages = this.aggregateLanguages(languageFrequency);
+    if (detectedLanguages.length === 0) {
+      this.logger.info(
+        `[PdfLanguageDetector] No languages detected from sampled pages; using default OCR languages: ${JSON.stringify(DEFAULT_OCR_LANGUAGES)}`
+      );
+      return {
+        detectedLanguages: [...DEFAULT_OCR_LANGUAGES],
+        reason: `No language detected in ${sampledPages} sampled pages`,
+        sampledPages,
+        totalPages: renderResult.pageCount,
+        source: "default"
+      };
+    }
+    this.logger.info(
+      `[PdfLanguageDetector] Languages detected from sampled pages: ${detectedLanguages.join(", ")}`
+    );
+    return {
+      detectedLanguages,
+      reason: `Languages detected in ${sampledPages} sampled pages`,
+      sampledPages,
+      totalPages: renderResult.pageCount,
+      source: "vlm"
+    };
+  }
+  selectSamplePages(totalPages, maxSamples) {
+    if (totalPages === 0) return [];
+    if (totalPages <= maxSamples) {
+      return Array.from({ length: totalPages }, (_, i) => i);
+    }
+    const trimCount = Math.max(1, Math.ceil(totalPages * EDGE_TRIM_RATIO));
+    const start = trimCount;
+    const end = totalPages - trimCount;
+    const eligibleCount = end - start;
+    if (eligibleCount <= 0) {
+      return [Math.floor(totalPages / 2)];
+    }
+    if (eligibleCount <= maxSamples) {
+      return Array.from({ length: eligibleCount }, (_, i) => start + i);
+    }
+    const step = eligibleCount / maxSamples;
+    return Array.from(
+      { length: maxSamples },
+      (_, i) => start + Math.floor(i * step)
+    );
+  }
+  async analyzeSamplePage(pageFile, pageNo, options) {
+    this.logger.debug(
+      `[PdfLanguageDetector] Analyzing page ${pageNo} for language...`
+    );
+    const imageData = new Uint8Array(readFileSync(pageFile));
+    const result = await LLMCaller.callVision({
+      schema: languageDetectionSchema,
+      messages: [
+        {
+          role: "user",
+          content: [
+            {
+              type: "text",
+              text: KOREAN_DOCUMENT_DETECTION_PROMPT
+            },
+            {
+              type: "image",
+              image: imageData,
+              mediaType: "image/png"
+            }
+          ]
+        }
+      ],
+      primaryModel: options.model,
+      maxRetries: options.maxRetries ?? DEFAULT_MAX_RETRIES,
+      temperature: options.temperature ?? 0,
+      abortSignal: options.abortSignal,
+      component: "PdfLanguageDetector",
+      phase: "language-detection"
+    });
+    options.aggregator?.track(result.usage);
+    const output = result.output;
+    const detectedLanguages = output.detectedLanguages.map(normalizeToBcp47).filter((tag) => tag !== null);
+    this.logger.debug(
+      `[PdfLanguageDetector] Page ${pageNo}: detectedLanguages=${detectedLanguages.join(",")}`
+    );
+    return detectedLanguages;
+  }
+  aggregateLanguages(languageFrequency) {
+    return [...languageFrequency.entries()].sort((a, b) => b[1] - a[1]).map(([language]) => language);
+  }
+};
+
+// src/errors/image-pdf-fallback-error.ts
+var ImagePdfFallbackError = class extends Error {
+  constructor(originalError, fallbackError) {
+    super(
+      `PDF conversion failed with fallback. Original: ${originalError.message}. Fallback: ${fallbackError.message}`
+    );
+    this.originalError = originalError;
+    this.fallbackError = fallbackError;
+  }
+  name = "ImagePdfFallbackError";
+};
+
+// src/processors/page-renderer.ts
+import { existsSync, mkdirSync, readdirSync } from "fs";
+import { join as join3 } from "path";
+var PROGRESS_LOG_PERCENT_STEP = 10;
+var PageRenderer = class {
+  constructor(logger) {
+    this.logger = logger;
+  }
+  lastLoggedPercent = 0;
+  /**
+   * Render all pages of a PDF to individual PNG files.
+   *
+   * Uses per-page rendering (`magick 'input.pdf[N]'`) when page count is known,
+   * limiting peak memory to ~15MB/page instead of loading all pages at once.
+   *
+   * @param pdfPath - Absolute path to the source PDF file
+   * @param outputDir - Directory where pages/ subdirectory will be created
+   * @param options - Rendering options
+   * @returns Render result with page count and file paths
+   */
+  async renderPages(pdfPath, outputDir, options) {
+    const dpi = options?.dpi ?? PAGE_RENDERING.DEFAULT_DPI;
+    const pagesDir = join3(outputDir, "pages");
+    if (!existsSync(pagesDir)) {
+      mkdirSync(pagesDir, { recursive: true });
+    }
+    const totalPages = await this.getPageCount(pdfPath);
+    if (totalPages > 0) {
+      this.logger.info(
+        `[PageRenderer] Rendering ${totalPages} pages at ${dpi} DPI...`
+      );
+      this.lastLoggedPercent = 0;
+      for (let i = 0; i < totalPages; i++) {
+        const result = await spawnAsync(
+          "magick",
+          [
+            "-density",
+            dpi.toString(),
+            `${pdfPath}[${i}]`,
+            "-background",
+            "white",
+            "-alpha",
+            "remove",
+            "-alpha",
+            "off",
+            join3(pagesDir, `page_${i}.png`)
+          ],
+          { captureStdout: false }
+        );
+        if (result.code !== 0) {
+          throw new Error(
+            `[PageRenderer] Failed to render page ${i + 1}/${totalPages}: ${result.stderr || "Unknown error"}`
+          );
+        }
+        this.logProgress(i + 1, totalPages);
+      }
+    } else {
+      this.logger.info(`[PageRenderer] Rendering PDF at ${dpi} DPI...`);
+      const result = await spawnAsync(
+        "magick",
+        [
+          "-density",
+          dpi.toString(),
+          pdfPath,
+          "-background",
+          "white",
+          "-alpha",
+          "remove",
+          "-alpha",
+          "off",
+          join3(pagesDir, "page_%d.png")
+        ],
+        { captureStdout: false }
+      );
+      if (result.code !== 0) {
+        throw new Error(
+          `[PageRenderer] Failed to render PDF pages: ${result.stderr || "Unknown error"}`
+        );
+      }
+    }
+    const pageFiles = readdirSync(pagesDir).filter((f) => f.startsWith("page_") && f.endsWith(".png")).sort((a, b) => {
+      const numA = parseInt(a.replace("page_", "").replace(".png", ""), 10);
+      const numB = parseInt(b.replace("page_", "").replace(".png", ""), 10);
+      return numA - numB;
+    }).map((f) => join3(pagesDir, f));
+    this.logger.info(
+      `[PageRenderer] Rendered ${pageFiles.length} pages to ${pagesDir}`
+    );
+    return {
+      pageCount: pageFiles.length,
+      pagesDir,
+      pageFiles
+    };
+  }
+  /**
+   * Log rendering progress at appropriate intervals (every 10%).
+   */
+  logProgress(current, total) {
+    const percent = Math.floor(current / total * 100);
+    if (percent >= this.lastLoggedPercent + PROGRESS_LOG_PERCENT_STEP || current === total) {
+      this.lastLoggedPercent = percent;
+      this.logger.info(
+        `[PageRenderer] Rendering pages: ${current}/${total} (${percent}%)`
+      );
+    }
+  }
+  /**
+   * Get total page count using pdfinfo.
+   * Returns 0 on failure (progress logging will be skipped).
+   */
+  async getPageCount(pdfPath) {
+    try {
+      const result = await spawnAsync("pdfinfo", [pdfPath]);
+      if (result.code !== 0) return 0;
+      const match = result.stdout.match(/^Pages:\s+(\d+)/m);
+      return match ? parseInt(match[1], 10) : 0;
+    } catch {
+      return 0;
+    }
+  }
+};
+
 // src/validators/document-type-validator.ts
-import { z } from "zod";
+import { z as z2 } from "zod";
 
 // src/errors/invalid-document-type-error.ts
 var InvalidDocumentTypeError = class extends Error {
@@ -1162,9 +1527,9 @@ NOT valid (these are NOT archaeological investigation reports):
 - Museum catalogs or exhibition guides`;
 
 // src/validators/document-type-validator.ts
-var documentTypeSchema = z.object({
-  isValid: z.boolean().describe("Whether this is an archaeological investigation report"),
-  reason: z.string().describe("Brief reason for the decision")
+var documentTypeSchema = z2.object({
+  isValid: z2.boolean().describe("Whether this is an archaeological investigation report"),
+  reason: z2.string().describe("Brief reason for the decision")
 });
 var DocumentTypeValidator = class {
   textExtractor;
@@ -1217,7 +1582,7 @@ import {
   copyFileSync,
   existsSync as existsSync3,
   mkdirSync as mkdirSync3,
-  readFileSync,
+  readFileSync as readFileSync2,
   readdirSync as readdirSync3,
   rmSync as rmSync2,
   writeFileSync as writeFileSync2
@@ -1357,13 +1722,13 @@ var DoclingDocumentMerger = class {
 import {
   createReadStream,
   createWriteStream as createWriteStream2,
-  existsSync,
-  mkdirSync,
-  readdirSync,
+  existsSync as existsSync2,
+  mkdirSync as mkdirSync2,
+  readdirSync as readdirSync2,
   rmSync,
   writeFileSync
 } from "fs";
-import { extname, join as join3 } from "path";
+import { extname, join as join4 } from "path";
 import { Transform } from "stream";
 import { pipeline as pipeline2 } from "stream/promises";
 import * as yauzl from "yauzl";
@@ -1575,9 +1940,9 @@ var ImageExtractor = class _ImageExtractor {
         }
         zipfile.readEntry();
         zipfile.on("entry", (entry) => {
-          const entryPath = join3(targetDir, entry.fileName);
+          const entryPath = join4(targetDir, entry.fileName);
           if (/\/$/.test(entry.fileName)) {
-            mkdirSync(entryPath, { recursive: true });
+            mkdirSync2(entryPath, { recursive: true });
             zipfile.readEntry();
           } else {
             zipfile.openReadStream(entry, (err2, readStream) => {
@@ -1585,7 +1950,7 @@ var ImageExtractor = class _ImageExtractor {
                 reject(err2 || new Error("Failed to open read stream"));
                 return;
               }
-              mkdirSync(join3(entryPath, ".."), { recursive: true });
+              mkdirSync2(join4(entryPath, ".."), { recursive: true });
               const writeStream = createWriteStream2(entryPath);
               readStream.pipe(writeStream);
               writeStream.on("finish", () => {
@@ -1609,7 +1974,7 @@ var ImageExtractor = class _ImageExtractor {
     const PREFIX = "data:image/png;base64,";
     const base64Content = base64Data.startsWith(PREFIX) ? base64Data.slice(PREFIX.length) : base64Data;
     const filename = `${prefix}_${index}.png`;
-    const filepath = join3(imagesDir, filename);
+    const filepath = join4(imagesDir, filename);
     const buffer = Buffer.from(base64Content, "base64");
     writeFileSync(filepath, buffer);
     return `${dirName}/${filename}`;
@@ -1643,7 +2008,7 @@ var ImageExtractor = class _ImageExtractor {
         }
         const base64Content = pending.slice(dataStart, quoteIdx);
         const filename = `image_${imageIndex}.png`;
-        const filepath = join3(imagesDir, filename);
+        const filepath = join4(imagesDir, filename);
         const buf = Buffer.from(base64Content, "base64");
         writeFileSync(filepath, buf);
         const relativePath = `images/${filename}`;
@@ -1687,19 +2052,19 @@ var ImageExtractor = class _ImageExtractor {
    */
   static async saveDocumentsWithExtractedImages(logger, outputDir, filename, jsonSourcePath, htmlSourcePath) {
     try {
-      if (existsSync(outputDir)) {
+      if (existsSync2(outputDir)) {
         rmSync(outputDir, { recursive: true, force: true });
       }
     } catch (e) {
       logger.warn("[PDFConverter] Failed to clear output directory:", e);
     }
-    mkdirSync(outputDir, { recursive: true });
+    mkdirSync2(outputDir, { recursive: true });
     const baseName = filename.replace(extname(filename), "");
-    const jsonPath = join3(outputDir, `${baseName}.json`);
+    const jsonPath = join4(outputDir, `${baseName}.json`);
     try {
-      const imagesDir = join3(outputDir, "images");
-      if (!existsSync(imagesDir)) {
-        mkdirSync(imagesDir, { recursive: true });
+      const imagesDir = join4(outputDir, "images");
+      if (!existsSync2(imagesDir)) {
+        mkdirSync2(imagesDir, { recursive: true });
       }
       const imageCount = await jqExtractBase64PngStringsStreaming(
         jsonSourcePath,
@@ -1733,11 +2098,11 @@ var ImageExtractor = class _ImageExtractor {
       throw e;
     }
     logger.info("[PDFConverter] Saved JSON:", jsonPath);
-    const htmlPath = join3(outputDir, `${baseName}.html`);
+    const htmlPath = join4(outputDir, `${baseName}.html`);
     try {
-      const imagesDir = join3(outputDir, "images");
-      if (!existsSync(imagesDir)) {
-        mkdirSync(imagesDir, { recursive: true });
+      const imagesDir = join4(outputDir, "images");
+      if (!existsSync2(imagesDir)) {
+        mkdirSync2(imagesDir, { recursive: true });
       }
       const htmlImageCount = await _ImageExtractor.extractImagesFromHtmlStream(
         htmlSourcePath,
@@ -1774,7 +2139,7 @@ var ImageExtractor = class _ImageExtractor {
   static async extractAndSaveDocumentsFromZip(logger, zipPath, extractDir, outputDir) {
     logger.info("[PDFConverter] Extracting ZIP file...");
     await _ImageExtractor.extractZip(zipPath, extractDir);
-    const files = readdirSync(extractDir);
+    const files = readdirSync2(extractDir);
     const jsonFile = files.find((f) => extname(f).toLowerCase() === ".json");
     const htmlFile = files.find((f) => extname(f).toLowerCase() === ".html");
     if (!jsonFile || !htmlFile) {
@@ -1782,8 +2147,8 @@ var ImageExtractor = class _ImageExtractor {
         `Expected one JSON and one HTML file in extracted directory. Found: ${files.join(", ")}`
       );
     }
-    const jsonPath = join3(extractDir, jsonFile);
-    const htmlPath = join3(extractDir, htmlFile);
+    const jsonPath = join4(extractDir, jsonFile);
+    const htmlPath = join4(extractDir, htmlFile);
     logger.info("[PDFConverter] Saving converted files to output...");
     await _ImageExtractor.saveDocumentsWithExtractedImages(
       logger,
@@ -1892,130 +2257,6 @@ var LocalFileServer = class {
 // src/utils/page-image-updater.ts
 import { rename as rename2 } from "fs/promises";
 import { join as join5 } from "path";
-
-// src/processors/page-renderer.ts
-import { existsSync as existsSync2, mkdirSync as mkdirSync2, readdirSync as readdirSync2 } from "fs";
-import { join as join4 } from "path";
-var PROGRESS_LOG_PERCENT_STEP = 10;
-var PageRenderer = class {
-  constructor(logger) {
-    this.logger = logger;
-  }
-  lastLoggedPercent = 0;
-  /**
-   * Render all pages of a PDF to individual PNG files.
-   *
-   * Uses per-page rendering (`magick 'input.pdf[N]'`) when page count is known,
-   * limiting peak memory to ~15MB/page instead of loading all pages at once.
-   *
-   * @param pdfPath - Absolute path to the source PDF file
-   * @param outputDir - Directory where pages/ subdirectory will be created
-   * @param options - Rendering options
-   * @returns Render result with page count and file paths
-   */
-  async renderPages(pdfPath, outputDir, options) {
-    const dpi = options?.dpi ?? PAGE_RENDERING.DEFAULT_DPI;
-    const pagesDir = join4(outputDir, "pages");
-    if (!existsSync2(pagesDir)) {
-      mkdirSync2(pagesDir, { recursive: true });
-    }
-    const totalPages = await this.getPageCount(pdfPath);
-    if (totalPages > 0) {
-      this.logger.info(
-        `[PageRenderer] Rendering ${totalPages} pages at ${dpi} DPI...`
-      );
-      this.lastLoggedPercent = 0;
-      for (let i = 0; i < totalPages; i++) {
-        const result = await spawnAsync(
-          "magick",
-          [
-            "-density",
-            dpi.toString(),
-            `${pdfPath}[${i}]`,
-            "-background",
-            "white",
-            "-alpha",
-            "remove",
-            "-alpha",
-            "off",
-            join4(pagesDir, `page_${i}.png`)
-          ],
-          { captureStdout: false }
-        );
-        if (result.code !== 0) {
-          throw new Error(
-            `[PageRenderer] Failed to render page ${i + 1}/${totalPages}: ${result.stderr || "Unknown error"}`
-          );
-        }
-        this.logProgress(i + 1, totalPages);
-      }
-    } else {
-      this.logger.info(`[PageRenderer] Rendering PDF at ${dpi} DPI...`);
-      const result = await spawnAsync(
-        "magick",
-        [
-          "-density",
-          dpi.toString(),
-          pdfPath,
-          "-background",
-          "white",
-          "-alpha",
-          "remove",
-          "-alpha",
-          "off",
-          join4(pagesDir, "page_%d.png")
-        ],
-        { captureStdout: false }
-      );
-      if (result.code !== 0) {
-        throw new Error(
-          `[PageRenderer] Failed to render PDF pages: ${result.stderr || "Unknown error"}`
-        );
-      }
-    }
-    const pageFiles = readdirSync2(pagesDir).filter((f) => f.startsWith("page_") && f.endsWith(".png")).sort((a, b) => {
-      const numA = parseInt(a.replace("page_", "").replace(".png", ""), 10);
-      const numB = parseInt(b.replace("page_", "").replace(".png", ""), 10);
-      return numA - numB;
-    }).map((f) => join4(pagesDir, f));
-    this.logger.info(
-      `[PageRenderer] Rendered ${pageFiles.length} pages to ${pagesDir}`
-    );
-    return {
-      pageCount: pageFiles.length,
-      pagesDir,
-      pageFiles
-    };
-  }
-  /**
-   * Log rendering progress at appropriate intervals (every 10%).
-   */
-  logProgress(current, total) {
-    const percent = Math.floor(current / total * 100);
-    if (percent >= this.lastLoggedPercent + PROGRESS_LOG_PERCENT_STEP || current === total) {
-      this.lastLoggedPercent = percent;
-      this.logger.info(
-        `[PageRenderer] Rendering pages: ${current}/${total} (${percent}%)`
-      );
-    }
-  }
-  /**
-   * Get total page count using pdfinfo.
-   * Returns 0 on failure (progress logging will be skipped).
-   */
-  async getPageCount(pdfPath) {
-    try {
-      const result = await spawnAsync("pdfinfo", [pdfPath]);
-      if (result.code !== 0) return 0;
-      const match = result.stdout.match(/^Pages:\s+(\d+)/m);
-      return match ? parseInt(match[1], 10) : 0;
-    } catch {
-      return 0;
-    }
-  }
-};
-
-// src/utils/page-image-updater.ts
 async function renderAndUpdatePageImages(pdfPath, outputDir, logger, logPrefix) {
   logger.info(`${logPrefix} Rendering page images with ImageMagick...`);
   const renderer = new PageRenderer(logger);
@@ -2127,6 +2368,7 @@ ${logPrefix} Task failed after ${elapsed}s: ${errorDetails}`
 // src/core/conversion-options-builder.ts
 import { omit } from "es-toolkit";
 function buildConversionOptions(options) {
+  const ocrLanguages = options.ocr_lang ?? DEFAULT_OCR_LANGUAGES;
   return {
     ...omit(options, [
       "num_threads",
@@ -2139,14 +2381,18 @@ function buildConversionOptions(options) {
       "chunkedConversion",
       "chunkSize",
       "chunkMaxRetries",
-      "documentValidationModel"
+      "documentValidationModel",
+      "languageDetectionModel"
     ]),
     to_formats: ["json", "html"],
     image_export_mode: "embedded",
+    // Docling currently reads this top-level field in addition to ocr_options.
+    // Keep it populated even when language detection is skipped.
+    ocr_lang: ocrLanguages,
     ocr_engine: "ocrmac",
     ocr_options: {
       kind: "ocrmac",
-      lang: options.ocr_lang ?? ["ko-KR", "en-US"],
+      lang: ocrLanguages,
       recognition: "accurate",
       framework: "livetext"
     },
@@ -2473,7 +2719,7 @@ var ChunkedPDFConverter = class {
    * pages/page_N.png, these pic_ files become orphaned.
    */
   cleanupOrphanedPicFiles(resultPath, imagesDir) {
-    const content = readFileSync(resultPath, "utf-8");
+    const content = readFileSync2(resultPath, "utf-8");
     const referencedPics = new Set(
       [...content.matchAll(/images\/pic_\d+\.png/g)].map(
         (m) => m[0].replace("images/", "")
@@ -2775,7 +3021,7 @@ import { join as join15 } from "path";
 
 // src/processors/post-docling-page-processor.ts
 import { buildLanguageDescription } from "@heripo/model";
-import { readFileSync as readFileSync3, writeFileSync as writeFileSync4 } from "fs";
+import { readFileSync as readFileSync4, writeFileSync as writeFileSync4 } from "fs";
 import { join as join10 } from "path";
 
 // src/prompts/text-correction-prompt.ts
@@ -2832,35 +3078,35 @@ Substitution rules for tc:
 If all correct: {"tc":[],"cc":[]}`;
 
 // src/types/vlm-text-correction-schema.ts
-import { z as z2 } from "zod/v4";
-var vlmTextCorrectionSchema = z2.object({
+import { z as z3 } from "zod/v4";
+var vlmTextCorrectionSchema = z3.object({
   /** Text element corrections (substitution-based) */
-  tc: z2.array(
-    z2.object({
+  tc: z3.array(
+    z3.object({
       /** Text element index (from prompt) */
-      i: z2.number().int().nonnegative(),
+      i: z3.number().int().nonnegative(),
       /** Substitutions: find/replace pairs applied left-to-right */
-      s: z2.array(
-        z2.object({
+      s: z3.array(
+        z3.object({
           /** Exact garbled substring to find */
-          f: z2.string(),
+          f: z3.string(),
           /** Corrected replacement text */
-          r: z2.string()
+          r: z3.string()
         })
       )
     })
   ),
   /** Table cell corrections */
-  cc: z2.array(
-    z2.object({
+  cc: z3.array(
+    z3.object({
       /** Table index (within the page) */
-      ti: z2.number().int().nonnegative(),
+      ti: z3.number().int().nonnegative(),
       /** Row index */
-      r: z2.number().int().nonnegative(),
+      r: z3.number().int().nonnegative(),
       /** Column index */
-      c: z2.number().int().nonnegative(),
+      c: z3.number().int().nonnegative(),
       /** Corrected cell text */
-      t: z2.string()
+      t: z3.string()
     })
   )
 });
@@ -2998,21 +3244,21 @@ function applyCorrections(doc, pageNo, corrections, logger) {
 }
 
 // src/processors/review-assistance/review-assistance-page-gate.ts
-import { existsSync as existsSync6, readFileSync as readFileSync2, writeFileSync as writeFileSync3 } from "fs";
+import { existsSync as existsSync6, readFileSync as readFileSync3, writeFileSync as writeFileSync3 } from "fs";
 import { join as join9 } from "path";
-import { z as z3 } from "zod/v4";
+import { z as z4 } from "zod/v4";
 var REVIEW_ASSISTANCE_PAGE_GATE_FILE = "review_assistance_page_gate.json";
 var REVIEW_ASSISTANCE_PAGE_GATE_MAX_RETRIES = 2;
 var REVIEW_ASSISTANCE_PAGE_GATE_TEMPERATURE = 0;
 var MAX_REASON_COUNT = 12;
 var MAX_CONTEXT_TEXT_LENGTH = 1800;
 var REVIEW_ASSISTANCE_PAGE_IMAGE_NOT_AVAILABLE_REASON = "page_image_not_available";
-var reviewAssistancePageGateSchema = z3.object({
-  eligible: z3.boolean(),
-  kind: z3.enum(["toc", "archaeological_data", "non_meaningful"]),
-  score: z3.number().min(0).max(100),
-  reasons: z3.array(z3.string()).max(MAX_REASON_COUNT),
-  exclusionReasons: z3.array(z3.string()).max(MAX_REASON_COUNT)
+var reviewAssistancePageGateSchema = z4.object({
+  eligible: z4.boolean(),
+  kind: z4.enum(["toc", "archaeological_data", "non_meaningful"]),
+  score: z4.number().min(0).max(100),
+  reasons: z4.array(z4.string()).max(MAX_REASON_COUNT),
+  exclusionReasons: z4.array(z4.string()).max(MAX_REASON_COUNT)
 });
 var REVIEW_ASSISTANCE_PAGE_GATE_PROMPT = `You are deciding whether a single PDF page should run structural Review Assistance after OCR text correction.
 
@@ -3149,7 +3395,7 @@ function readReviewAssistancePageGateReport(outputDir) {
   const path = join9(outputDir, REVIEW_ASSISTANCE_PAGE_GATE_FILE);
   if (!existsSync6(path)) return void 0;
   const report = JSON.parse(
-    readFileSync2(path, "utf-8")
+    readFileSync3(path, "utf-8")
   );
   return new Map(report.pages.map((page) => [page.pageNo, page]));
 }
@@ -3167,7 +3413,7 @@ function writeReviewAssistancePageGateReport(outputDir, pages) {
 
 // src/processors/post-docling-page-processor.ts
 var DEFAULT_CONCURRENCY = 1;
-var DEFAULT_MAX_RETRIES = 3;
+var DEFAULT_MAX_RETRIES2 = 3;
 var DEFAULT_TEMPERATURE = 0;
 var PostDoclingPageProcessor = class {
   constructor(logger) {
@@ -3185,7 +3431,7 @@ var PostDoclingPageProcessor = class {
   async correctAndSave(outputDir, model, options) {
     this.logger.info("[PostDoclingPageProcessor] Starting text correction...");
     const resultPath = join10(outputDir, "result.json");
-    const doc = JSON.parse(readFileSync3(resultPath, "utf-8"));
+    const doc = JSON.parse(readFileSync4(resultPath, "utf-8"));
     const allPageNumbers = this.getPageNumbers(doc);
     if (allPageNumbers.length === 0) {
       this.logger.info("[PostDoclingPageProcessor] No pages to process");
@@ -3327,7 +3573,7 @@ var PostDoclingPageProcessor = class {
           }
         ],
         primaryModel: model,
-        maxRetries: options?.maxRetries ?? DEFAULT_MAX_RETRIES,
+        maxRetries: options?.maxRetries ?? DEFAULT_MAX_RETRIES2,
         temperature: options?.temperature ?? DEFAULT_TEMPERATURE,
         abortSignal: options?.abortSignal,
         component: "PostDoclingPageProcessor",
@@ -3493,21 +3739,21 @@ var PostDoclingPageProcessor = class {
    */
   readPageImage(outputDir, pageNo) {
     const imagePath = join10(outputDir, "pages", `page_${pageNo - 1}.png`);
-    return new Uint8Array(readFileSync3(imagePath));
+    return new Uint8Array(readFileSync4(imagePath));
   }
 };
 
 // src/processors/review-assistance/review-assistance-runner.ts
-import { copyFileSync as copyFileSync2, existsSync as existsSync9, readFileSync as readFileSync5, writeFileSync as writeFileSync6 } from "fs";
+import { copyFileSync as copyFileSync2, existsSync as existsSync9, readFileSync as readFileSync6, writeFileSync as writeFileSync6 } from "fs";
 import { readFile } from "fs/promises";
 import { join as join14 } from "path";
 
 // src/types/review-assistance-schema.ts
-import { z as z4 } from "zod/v4";
+import { z as z5 } from "zod/v4";
 var REVIEW_ASSISTANCE_RATIONALE_MAX_LENGTH = 2e3;
 var REVIEW_ASSISTANCE_EVIDENCE_MAX_LENGTH = 2e3;
 var REVIEW_ASSISTANCE_PAGE_NOTE_MAX_LENGTH = 2e3;
-var reviewAssistanceCommandOpSchema = z4.enum([
+var reviewAssistanceCommandOpSchema = z5.enum([
   "replaceText",
   "addText",
   "updateTextRole",
@@ -3525,18 +3771,18 @@ var reviewAssistanceCommandOpSchema = z4.enum([
   "linkFootnote",
   "moveNode"
 ]);
-var reviewAssistanceRawCommandSchema = z4.object({
+var reviewAssistanceRawCommandSchema = z5.object({
   op: reviewAssistanceCommandOpSchema,
-  targetRef: z4.string().nullable(),
-  payload: z4.record(z4.string(), z4.unknown()),
-  confidence: z4.number().min(0).max(1),
-  rationale: z4.string().max(REVIEW_ASSISTANCE_RATIONALE_MAX_LENGTH),
-  evidence: z4.string().max(REVIEW_ASSISTANCE_EVIDENCE_MAX_LENGTH).nullable()
+  targetRef: z5.string().nullable(),
+  payload: z5.record(z5.string(), z5.unknown()),
+  confidence: z5.number().min(0).max(1),
+  rationale: z5.string().max(REVIEW_ASSISTANCE_RATIONALE_MAX_LENGTH),
+  evidence: z5.string().max(REVIEW_ASSISTANCE_EVIDENCE_MAX_LENGTH).nullable()
 });
-var reviewAssistancePageSchema = z4.object({
-  pageNo: z4.number().int().positive(),
-  commands: z4.array(reviewAssistanceRawCommandSchema).max(80),
-  pageNotes: z4.array(z4.string().max(REVIEW_ASSISTANCE_PAGE_NOTE_MAX_LENGTH)).max(10)
+var reviewAssistancePageSchema = z5.object({
+  pageNo: z5.number().int().positive(),
+  commands: z5.array(reviewAssistanceRawCommandSchema).max(80),
+  pageNotes: z5.array(z5.string().max(REVIEW_ASSISTANCE_PAGE_NOTE_MAX_LENGTH)).max(10)
 });
 
 // src/prompts/review-assistance-prompt.ts
@@ -5029,7 +5275,7 @@ var PictureSplitCandidateDetector = class {
 };
 
 // src/processors/review-assistance/review-assistance-checkpoint-store.ts
-import { existsSync as existsSync7, readFileSync as readFileSync4, writeFileSync as writeFileSync5 } from "fs";
+import { existsSync as existsSync7, readFileSync as readFileSync5, writeFileSync as writeFileSync5 } from "fs";
 import { join as join12 } from "path";
 var CHECKPOINT_FILE = "review_assistance_checkpoint.json";
 var ReviewAssistanceCheckpointStore = class _ReviewAssistanceCheckpointStore {
@@ -5111,7 +5357,7 @@ var ReviewAssistanceCheckpointStore = class _ReviewAssistanceCheckpointStore {
     }
     try {
       const parsed = JSON.parse(
-        readFileSync4(path, "utf-8")
+        readFileSync5(path, "utf-8")
       );
       if (parsed.schemaVersion !== 1 || parsed.runId !== runId) {
         return this.empty(runId, now);
@@ -7900,7 +8146,7 @@ var ReviewAssistanceRunner = class {
       copyFileSync2(reviewOriginPath, ocrOriginPath);
     }
     const doc = JSON.parse(
-      readFileSync5(reviewOriginPath, "utf-8")
+      readFileSync6(reviewOriginPath, "utf-8")
     );
     const pageTexts = options.pageTexts ?? await PdfTextExtractor.tryExtract(
       this.logger,
@@ -9423,8 +9669,13 @@ var PDFConverter = class {
   async convert(url, reportId, onComplete, cleanupAfterCallback, options, abortSignal) {
     this.logger.info("[PDFConverter] Converting:", url);
     const aggregator = options.aggregator ?? new LLMTokenUsageAggregator();
-    const trackedOptions = { ...options, aggregator };
     const pdfPath = url.startsWith("file://") ? url.slice(7) : void 0;
+    const trackedOptions = await this.withDetectedLanguages(
+      pdfPath,
+      reportId,
+      { ...options, aggregator },
+      abortSignal
+    );
     const correctedOnComplete = new PostDoclingCorrectionPipeline(
       this.logger
     ).wrapCallback(pdfPath, reportId, trackedOptions, onComplete, abortSignal);
@@ -9487,6 +9738,58 @@ var PDFConverter = class {
     }
     return this.buildTokenReport(aggregator) ?? conversionReport;
   }
+  async withDetectedLanguages(pdfPath, reportId, options, abortSignal) {
+    if (options.ocr_lang && options.ocr_lang.length > 0) {
+      this.logger.info(
+        `[PDFConverter] OCR languages provided: ${JSON.stringify(options.ocr_lang)}`
+      );
+      return options;
+    }
+    if (!pdfPath) {
+      this.logger.info(
+        "[PDFConverter] Local PDF not available; OCR languages will use defaults"
+      );
+      return {
+        ...options,
+        ocr_lang: [...DEFAULT_OCR_LANGUAGES]
+      };
+    }
+    const languageDetectionDir = join16(
+      process.cwd(),
+      "output",
+      reportId,
+      "_language_detection"
+    );
+    const detector = new PdfLanguageDetector(
+      this.logger,
+      new PageRenderer(this.logger),
+      new PdfTextExtractor(this.logger)
+    );
+    try {
+      const result = await detector.detect(pdfPath, languageDetectionDir, {
+        model: options.languageDetectionModel,
+        aggregator: options.aggregator,
+        abortSignal
+      });
+      this.logger.info(
+        `[PDFConverter] OCR languages detected: ${JSON.stringify(result.detectedLanguages)} (${result.reason})`
+      );
+      if (options.onTokenUsage && options.aggregator) {
+        const tokenReport = this.buildTokenReport(options.aggregator);
+        if (tokenReport) {
+          options.onTokenUsage(tokenReport);
+        }
+      }
+      return {
+        ...options,
+        ocr_lang: result.detectedLanguages
+      };
+    } finally {
+      if (existsSync10(languageDetectionDir)) {
+        rmSync7(languageDetectionDir, { recursive: true, force: true });
+      }
+    }
+  }
   /**
    * Build a token usage report from the aggregator.
    * Returns null when no LLM calls were tracked.
@@ -9645,7 +9948,7 @@ var PDFParser = class {
       this.baseUrl = void 0;
     }
     this.timeout = timeout;
-    this.venvPath = venvPath || join16(process.cwd(), ".venv");
+    this.venvPath = venvPath || join17(process.cwd(), ".venv");
     this.killExistingProcess = killExistingProcess;
     this.enableImagePdfFallback = enableImagePdfFallback;
   }
@@ -9942,7 +10245,7 @@ var META_DESCRIPTION_PATTERNS_EN = [
 ];
 var REPETITIVE_PATTERN_RATIO_THRESHOLD = 0.3;
 var REPETITIVE_PATTERN_MIN_REPEATS = 5;
-var HANGUL_REGEX = /[\uAC00-\uD7AF\u1100-\u11FF]/g;
+var HANGUL_REGEX2 = /[\uAC00-\uD7AF\u1100-\u11FF]/g;
 var CJK_REGEX = /[\u4E00-\u9FFF]/g;
 var VlmResponseValidator = class {
   /**
@@ -10010,7 +10313,7 @@ var VlmResponseValidator = class {
     if (nonWhitespace.length < MIN_CONTENT_LENGTH) {
       return null;
     }
-    const hangulCount = allContent.match(HANGUL_REGEX)?.length ?? 0;
+    const hangulCount = allContent.match(HANGUL_REGEX2)?.length ?? 0;
     const cjkCount = allContent.match(CJK_REGEX)?.length ?? 0;
     const koreanCjkCount = hangulCount + cjkCount;
     const ratio = koreanCjkCount / nonWhitespace.length;