@heripo/pdf-parser 0.1.14 → 0.1.16

package/dist/index.d.cts

@@ -41,6 +41,8 @@ type PDFConvertOptions = Omit<ConversionOptions, 'to_formats' | 'image_export_mo
     chunkSize?: number;
     /** Max retry attempts per failed chunk (default: CHUNKED_CONVERSION.DEFAULT_MAX_RETRIES) */
     chunkMaxRetries?: number;
+    /** LLM model for document type validation (opt-in: skipped when not set) */
+    documentValidationModel?: LanguageModel;
 };
 /** Result of strategy-based conversion */
 interface ConvertWithStrategyResult {
@@ -179,6 +181,17 @@ declare class ImagePdfFallbackError extends Error {
     constructor(originalError: Error, fallbackError: Error);
 }
 
+/**
+ * Error thrown when the uploaded PDF does not appear to be
+ * a Korean archaeological investigation report.
+ */
+declare class InvalidDocumentTypeError extends Error {
+    readonly reason: string;
+    readonly name = "InvalidDocumentTypeError";
+    readonly code = "INVALID_DOCUMENT_TYPE";
+    constructor(reason: string);
+}
+
 /**
  * Intermediate format produced by VLM page-by-page processing.
  * Intentionally kept simple so VLM prompts stay short and accurate.
@@ -287,4 +300,4 @@ declare class VlmResponseValidator {
     private static detectRepetitivePattern;
 }
 
-export { type ConversionCompleteCallback, type ConvertWithStrategyResult, ImagePdfFallbackError, type PDFConvertOptions, PDFParser, type VlmPageQuality, type VlmQualityIssue, type VlmQualityIssueType, VlmResponseValidator, type VlmValidationResult };
+export { type ConversionCompleteCallback, type ConvertWithStrategyResult, ImagePdfFallbackError, InvalidDocumentTypeError, type PDFConvertOptions, PDFParser, type VlmPageQuality, type VlmQualityIssue, type VlmQualityIssueType, VlmResponseValidator, type VlmValidationResult };

package/dist/index.d.ts

@@ -41,6 +41,8 @@ type PDFConvertOptions = Omit<ConversionOptions, 'to_formats' | 'image_export_mo
     chunkSize?: number;
     /** Max retry attempts per failed chunk (default: CHUNKED_CONVERSION.DEFAULT_MAX_RETRIES) */
     chunkMaxRetries?: number;
+    /** LLM model for document type validation (opt-in: skipped when not set) */
+    documentValidationModel?: LanguageModel;
 };
 /** Result of strategy-based conversion */
 interface ConvertWithStrategyResult {
@@ -179,6 +181,17 @@ declare class ImagePdfFallbackError extends Error {
     constructor(originalError: Error, fallbackError: Error);
 }
 
+/**
+ * Error thrown when the uploaded PDF does not appear to be
+ * a Korean archaeological investigation report.
+ */
+declare class InvalidDocumentTypeError extends Error {
+    readonly reason: string;
+    readonly name = "InvalidDocumentTypeError";
+    readonly code = "INVALID_DOCUMENT_TYPE";
+    constructor(reason: string);
+}
+
 /**
  * Intermediate format produced by VLM page-by-page processing.
  * Intentionally kept simple so VLM prompts stay short and accurate.
@@ -287,4 +300,4 @@ declare class VlmResponseValidator {
     private static detectRepetitivePattern;
 }
 
-export { type ConversionCompleteCallback, type ConvertWithStrategyResult, ImagePdfFallbackError, type PDFConvertOptions, PDFParser, type VlmPageQuality, type VlmQualityIssue, type VlmQualityIssueType, VlmResponseValidator, type VlmValidationResult };
+export { type ConversionCompleteCallback, type ConvertWithStrategyResult, ImagePdfFallbackError, InvalidDocumentTypeError, type PDFConvertOptions, PDFParser, type VlmPageQuality, type VlmQualityIssue, type VlmQualityIssueType, VlmResponseValidator, type VlmValidationResult };

package/dist/index.js

@@ -1484,6 +1484,32 @@ var PdfTextExtractor = class {
     }
     return result.stdout;
   }
+  /**
+   * Extract text from a range of PDF pages using a single pdftotext invocation.
+   * Returns empty string on failure (logged as warning).
+   *
+   * @param pdfPath - Absolute path to the source PDF file
+   * @param firstPage - First page number (1-based)
+   * @param lastPage - Last page number (1-based, inclusive)
+   */
+  async extractPageRange(pdfPath, firstPage, lastPage) {
+    const result = await spawnAsync("pdftotext", [
+      "-f",
+      firstPage.toString(),
+      "-l",
+      lastPage.toString(),
+      "-layout",
+      pdfPath,
+      "-"
+    ]);
+    if (result.code !== 0) {
+      this.logger.warn(
+        `[PdfTextExtractor] pdftotext failed for pages ${firstPage}-${lastPage}: ${result.stderr || "Unknown error"}`
+      );
+      return "";
+    }
+    return result.stdout;
+  }
   /**
    * Extract text from a single PDF page using pdftotext.
    * Returns empty string on failure (logged as warning).
@@ -2376,6 +2402,94 @@ async function getTaskFailureDetails(task, logger, logPrefix) {
   return "unable to retrieve error details";
 }
 
+// src/validators/document-type-validator.ts
+import { z as z3 } from "zod";
+
+// src/errors/invalid-document-type-error.ts
+var InvalidDocumentTypeError = class extends Error {
+  constructor(reason) {
+    super(
+      `The uploaded PDF does not appear to be a Korean archaeological investigation report. Reason: ${reason}`
+    );
+    this.reason = reason;
+  }
+  name = "InvalidDocumentTypeError";
+  code = "INVALID_DOCUMENT_TYPE";
+};
+
+// src/validators/document-type-validator.ts
+var SYSTEM_PROMPT = `You are given text extracted from the first and last pages of a PDF document.
+Determine if this document is an archaeological investigation report from any country.
+
+Valid types include (in any language):
+- Excavation report (\uBC1C\uAD74\uC870\uC0AC\uBCF4\uACE0\uC11C)
+- Trial excavation report (\uC2DC\uAD74\uC870\uC0AC\uBCF4\uACE0\uC11C)
+- Surface survey report (\uC9C0\uD45C\uC870\uC0AC\uBCF4\uACE0\uC11C)
+- Detailed excavation report (\uC815\uBC00\uBC1C\uAD74\uC870\uC0AC\uBCF4\uACE0\uC11C)
+- Underwater excavation report (\uC218\uC911\uBC1C\uAD74\uC870\uC0AC\uBCF4\uACE0\uC11C)
+- Salvage excavation report
+- Archaeological assessment report
+- Any other archaeological fieldwork investigation report
+
+NOT valid (these are NOT archaeological investigation reports):
+- Repair/restoration reports (\uC218\uB9AC\uBCF4\uACE0\uC11C)
+- Simple measurement reports (\uB2E8\uC21C \uC2E4\uCE21 \uBCF4\uACE0\uC11C)
+- Architectural investigation reports (\uAC74\uCD95\uC870\uC0AC\uBCF4\uACE0\uC11C)
+- Academic research reports (\uD559\uC220\uC870\uC0AC\uBCF4\uACE0\uC11C)
+- Environmental impact assessments (\uD658\uACBD\uC601\uD5A5\uD3C9\uAC00)
+- General academic papers or textbooks about archaeology
+- Conservation/preservation reports
+- Museum catalogs or exhibition guides`;
+var documentTypeSchema = z3.object({
+  isValid: z3.boolean().describe("Whether this is an archaeological investigation report"),
+  reason: z3.string().describe("Brief reason for the decision")
+});
+var DocumentTypeValidator = class {
+  textExtractor;
+  constructor(textExtractor) {
+    this.textExtractor = textExtractor;
+  }
+  /**
+   * Validate that the PDF at the given path is an archaeological investigation report.
+   *
+   * @throws {InvalidDocumentTypeError} if the document is not a valid report type
+   */
+  async validate(pdfPath, model, options) {
+    const totalPages = await this.textExtractor.getPageCount(pdfPath);
+    if (totalPages === 0) return;
+    const frontText = await this.textExtractor.extractPageRange(
+      pdfPath,
+      1,
+      Math.min(10, totalPages)
+    );
+    let backText = "";
+    if (totalPages > 20) {
+      backText = await this.textExtractor.extractPageRange(
+        pdfPath,
+        Math.max(1, totalPages - 9),
+        totalPages
+      );
+    }
+    const combinedText = (frontText + "\n" + backText).trim();
+    if (combinedText.length === 0) return;
+    const result = await LLMCaller.call({
+      schema: documentTypeSchema,
+      systemPrompt: SYSTEM_PROMPT,
+      userPrompt: `--- Document text (first and last pages) ---
+${combinedText}`,
+      primaryModel: model,
+      maxRetries: 2,
+      temperature: 0,
+      abortSignal: options?.abortSignal,
+      component: "DocumentTypeValidator",
+      phase: "validation"
+    });
+    if (!result.output.isValid) {
+      throw new InvalidDocumentTypeError(result.output.reason);
+    }
+  }
+};
+
 // src/core/chunked-pdf-converter.ts
 import {
   copyFileSync,
@@ -3003,8 +3117,27 @@ var PDFConverter = class {
     this.enableImagePdfFallback = enableImagePdfFallback;
     this.timeout = timeout;
   }
+  documentTypeValidated = false;
+  /**
+   * Validate that the PDF is a Korean archaeological investigation report.
+   * Skipped when no documentValidationModel is configured or for non-local URLs.
+   * Only runs once per converter instance (flag prevents duplicate checks on recursive calls).
+   */
+  async validateDocumentType(url, options, abortSignal) {
+    if (this.documentTypeValidated) return;
+    this.documentTypeValidated = true;
+    if (!options.documentValidationModel) return;
+    const pdfPath = url.startsWith("file://") ? url.slice(7) : null;
+    if (!pdfPath) return;
+    const textExtractor = new PdfTextExtractor(this.logger);
+    const validator = new DocumentTypeValidator(textExtractor);
+    await validator.validate(pdfPath, options.documentValidationModel, {
+      abortSignal
+    });
+  }
   async convert(url, reportId, onComplete, cleanupAfterCallback, options, abortSignal) {
     this.logger.info("[PDFConverter] Converting:", url);
+    await this.validateDocumentType(url, options, abortSignal);
     if (options.chunkedConversion && url.startsWith("file://")) {
       const chunked = new ChunkedPDFConverter(
         this.logger,
@@ -3059,6 +3192,7 @@ var PDFConverter = class {
     const aggregator = options.aggregator ?? new LLMTokenUsageAggregator();
     const trackedOptions = { ...options, aggregator };
     const pdfPath = url.startsWith("file://") ? url.slice(7) : null;
+    await this.validateDocumentType(url, trackedOptions, abortSignal);
     const strategy = await this.determineStrategy(
       pdfPath,
       reportId,
@@ -3385,7 +3519,8 @@ var PDFConverter = class {
         "onTokenUsage",
         "chunkedConversion",
         "chunkSize",
-        "chunkMaxRetries"
+        "chunkMaxRetries",
+        "documentValidationModel"
       ]),
       to_formats: ["json", "html"],
       image_export_mode: "embedded",
@@ -4086,6 +4221,7 @@ var VlmResponseValidator = class {
 };
 export {
   ImagePdfFallbackError,
+  InvalidDocumentTypeError,
   PDFParser,
   VlmResponseValidator
 };