@heripo/pdf-parser 0.1.32 → 0.1.34

package/dist/index.d.cts

@@ -9,10 +9,20 @@ type ReviewAssistanceTaskId = 'text_ocr_hanja' | 'text_integrity' | 'text_role_f
 
 interface PDFCorrectionModelOptions {
     textCorrection: LanguageModel;
+    /** textCorrection 실패(예: lmstudio 400) 시 LLMCaller fallback. */
+    textCorrectionFallback?: LanguageModel;
     pageGate: LanguageModel;
+    /** pageGate(page-eligibility) 실패 시 fallback. */
+    pageGateFallback?: LanguageModel;
     reviewAssistance: LanguageModel;
+    /** review-assistance 공통 fallback (task별 미지정 시 사용). */
+    reviewAssistanceFallback?: LanguageModel;
     reviewAssistanceTasks?: Partial<Record<ReviewAssistanceTaskId, LanguageModel>>;
+    /** review-assistance task별 fallback. */
+    reviewAssistanceTasksFallback?: Partial<Record<ReviewAssistanceTaskId, LanguageModel>>;
     tableCorrection?: LanguageModel;
+    /** tableCorrection 실패 시 fallback. */
+    tableCorrectionFallback?: LanguageModel;
 }
 interface PDFCorrectionConcurrencyOptions {
     pages?: number;
@@ -93,6 +103,8 @@ type PDFConvertOptions = Omit<ConversionOptions, 'to_formats' | 'image_export_mo
     chunkMaxRetries?: number;
     /** Vision model for document language detection when the PDF text layer is insufficient */
     languageDetectionModel?: LanguageModel;
+    /** languageDetectionModel 실패 시 fallback. */
+    languageDetectionFallbackModel?: LanguageModel;
     /** LLM model for document type validation (opt-in: skipped when not set) */
     documentValidationModel?: LanguageModel;
 };

package/dist/index.d.ts

@@ -9,10 +9,20 @@ type ReviewAssistanceTaskId = 'text_ocr_hanja' | 'text_integrity' | 'text_role_f
 
 interface PDFCorrectionModelOptions {
     textCorrection: LanguageModel;
+    /** textCorrection 실패(예: lmstudio 400) 시 LLMCaller fallback. */
+    textCorrectionFallback?: LanguageModel;
     pageGate: LanguageModel;
+    /** pageGate(page-eligibility) 실패 시 fallback. */
+    pageGateFallback?: LanguageModel;
     reviewAssistance: LanguageModel;
+    /** review-assistance 공통 fallback (task별 미지정 시 사용). */
+    reviewAssistanceFallback?: LanguageModel;
     reviewAssistanceTasks?: Partial<Record<ReviewAssistanceTaskId, LanguageModel>>;
+    /** review-assistance task별 fallback. */
+    reviewAssistanceTasksFallback?: Partial<Record<ReviewAssistanceTaskId, LanguageModel>>;
     tableCorrection?: LanguageModel;
+    /** tableCorrection 실패 시 fallback. */
+    tableCorrectionFallback?: LanguageModel;
 }
 interface PDFCorrectionConcurrencyOptions {
     pages?: number;
@@ -93,6 +103,8 @@ type PDFConvertOptions = Omit<ConversionOptions, 'to_formats' | 'image_export_mo
     chunkMaxRetries?: number;
     /** Vision model for document language detection when the PDF text layer is insufficient */
     languageDetectionModel?: LanguageModel;
+    /** languageDetectionModel 실패 시 fallback. */
+    languageDetectionFallbackModel?: LanguageModel;
     /** LLM model for document type validation (opt-in: skipped when not set) */
     documentValidationModel?: LanguageModel;
 };

package/dist/index.js

@@ -138,6 +138,8 @@ function detectProvider(model) {
   if (providerId.includes("google")) return "google";
   if (providerId.includes("anthropic")) return "anthropic";
   if (providerId.includes("together")) return "togetherai";
+  if (providerId.includes("ollama")) return "ollama";
+  if (providerId.includes("lmstudio")) return "lmstudio";
   return "unknown";
 }
 var LLMCaller = class {
@@ -225,14 +227,18 @@ var LLMCaller = class {
    *
    * Strategy per provider:
    * - OpenAI / Anthropic / Google Gemini: `Output.object()` with schema retry
-   * - Together AI / unknown: forced tool call pattern
+   * - Together AI / Ollama / unknown: forced tool call pattern
+   *
+   * Ollama uses tool-call because MLX backends ignore the `format` grammar
+   * that `Output.object()` relies on, and gguf's grammar is unstable once
+   * thinking is disabled. Applies to both text and vision paths.
    *
    * Retries up to MAX_STRUCTURED_OUTPUT_RETRIES times on NoObjectGeneratedError
    * (schema mismatch), re-throwing the last error if all attempts fail.
    */
   static async generateStructuredOutput(model, schema, promptParams) {
     const providerType = detectProvider(model);
-    if (providerType === "togetherai" || providerType === "unknown") {
+    if (providerType === "togetherai" || providerType === "ollama" || providerType === "unknown") {
       return this.generateViaToolCall(model, schema, promptParams);
     }
     let lastError;
@@ -337,6 +343,29 @@ var LLMCaller = class {
 function formatTokens(usage) {
   return `${usage.inputTokens} input, ${usage.outputTokens} output, ${usage.totalTokens} total`;
 }
+function emptyUsage() {
+  return { inputTokens: 0, outputTokens: 0, totalTokens: 0 };
+}
+function addInto(target, src) {
+  target.inputTokens += src.inputTokens;
+  target.outputTokens += src.outputTokens;
+  target.totalTokens += src.totalTokens;
+}
+function sumUsage(a, b) {
+  return {
+    inputTokens: (a?.inputTokens ?? 0) + (b?.inputTokens ?? 0),
+    outputTokens: (a?.outputTokens ?? 0) + (b?.outputTokens ?? 0),
+    totalTokens: (a?.totalTokens ?? 0) + (b?.totalTokens ?? 0)
+  };
+}
+function accumulateModel(bucket, modelName, usage) {
+  let entry = bucket.get(modelName);
+  if (!entry) {
+    entry = emptyUsage();
+    bucket.set(modelName, entry);
+  }
+  addInto(entry, usage);
+}
 var LLMTokenUsageAggregator = class {
   usage = {};
   /**
@@ -349,21 +378,15 @@ var LLMTokenUsageAggregator = class {
       this.usage[usage.component] = {
         component: usage.component,
         phases: {},
-        total: {
-          inputTokens: 0,
-          outputTokens: 0,
-          totalTokens: 0
-        }
+        total: emptyUsage()
       };
     }
     const component = this.usage[usage.component];
     if (!component.phases[usage.phase]) {
       component.phases[usage.phase] = {
-        total: {
-          inputTokens: 0,
-          outputTokens: 0,
-          totalTokens: 0
-        },
+        primary: /* @__PURE__ */ new Map(),
+        fallback: /* @__PURE__ */ new Map(),
+        total: emptyUsage(),
         metadata: []
       };
     }
@@ -372,41 +395,17 @@ var LLMTokenUsageAggregator = class {
       phase.metadata.push(usage.metadata);
     }
     if (usage.model === "primary") {
-      if (!phase.primary) {
-        phase.primary = {
-          modelName: usage.modelName,
-          inputTokens: 0,
-          outputTokens: 0,
-          totalTokens: 0
-        };
-      }
-      phase.primary.inputTokens += usage.inputTokens;
-      phase.primary.outputTokens += usage.outputTokens;
-      phase.primary.totalTokens += usage.totalTokens;
+      accumulateModel(phase.primary, usage.modelName, usage);
     } else if (usage.model === "fallback") {
-      if (!phase.fallback) {
-        phase.fallback = {
-          modelName: usage.modelName,
-          inputTokens: 0,
-          outputTokens: 0,
-          totalTokens: 0
-        };
-      }
-      phase.fallback.inputTokens += usage.inputTokens;
-      phase.fallback.outputTokens += usage.outputTokens;
-      phase.fallback.totalTokens += usage.totalTokens;
+      accumulateModel(phase.fallback, usage.modelName, usage);
     }
-    phase.total.inputTokens += usage.inputTokens;
-    phase.total.outputTokens += usage.outputTokens;
-    phase.total.totalTokens += usage.totalTokens;
-    component.total.inputTokens += usage.inputTokens;
-    component.total.outputTokens += usage.outputTokens;
-    component.total.totalTokens += usage.totalTokens;
+    addInto(phase.total, usage);
+    addInto(component.total, usage);
   }
   /**
    * Get aggregated usage grouped by component
    *
-   * @returns Array of component aggregates with phase breakdown
+   * @returns Array of component aggregates with per-model phase breakdown
    */
   getByComponent() {
     return Object.values(this.usage);
@@ -415,8 +414,16 @@ var LLMTokenUsageAggregator = class {
    * Get token usage report in structured JSON format
    *
    * Converts internal usage data to external TokenUsageReport format suitable
-   * for serialization and reporting. The report includes component breakdown,
-   * phase-level details, and both primary and fallback model usage.
+   * for serialization and reporting.
+   *
+   * Each (phase, model) pair becomes its own PhaseUsageReport entry. A phase
+   * that used a single primary (and/or a single fallback) model yields exactly
+   * one entry — identical to the legacy shape — while a phase that mixed models
+   * yields one entry per model, all sharing the same `phase` name. Every
+   * (phase, tier, modelName) combination appears in exactly one entry, so
+   * consumers that key by `${component}|${phase}|${tier}|${modelName}`
+   * (heripo-web's token-usage emitter / ledger recorder) attribute each model's
+   * tokens — and cost — correctly without double counting.
    *
    * @returns Structured token usage report with components and total
    */
@@ -425,34 +432,41 @@ var LLMTokenUsageAggregator = class {
     for (const component of Object.values(this.usage)) {
       const phases = [];
       for (const [phaseName, phaseData] of Object.entries(component.phases)) {
-        const phaseReport = {
-          phase: phaseName,
-          total: {
-            inputTokens: phaseData.total.inputTokens,
-            outputTokens: phaseData.total.outputTokens,
-            totalTokens: phaseData.total.totalTokens
-          }
-        };
-        if (phaseData.metadata.length > 0) {
-          phaseReport.metadata = [...phaseData.metadata];
-        }
-        if (phaseData.primary) {
-          phaseReport.primary = {
-            modelName: phaseData.primary.modelName,
-            inputTokens: phaseData.primary.inputTokens,
-            outputTokens: phaseData.primary.outputTokens,
-            totalTokens: phaseData.primary.totalTokens
+        const primaryEntries = [...phaseData.primary.entries()];
+        const fallbackEntries = [...phaseData.fallback.entries()];
+        const entryCount = Math.max(
+          primaryEntries.length,
+          fallbackEntries.length
+        );
+        if (entryCount === 0) {
+          const phaseReport = {
+            phase: phaseName,
+            total: { ...phaseData.total }
           };
+          if (phaseData.metadata.length > 0) {
+            phaseReport.metadata = [...phaseData.metadata];
+          }
+          phases.push(phaseReport);
+          continue;
         }
-        if (phaseData.fallback) {
-          phaseReport.fallback = {
-            modelName: phaseData.fallback.modelName,
-            inputTokens: phaseData.fallback.inputTokens,
-            outputTokens: phaseData.fallback.outputTokens,
-            totalTokens: phaseData.fallback.totalTokens
+        for (let i = 0; i < entryCount; i++) {
+          const primary = primaryEntries[i];
+          const fallback = fallbackEntries[i];
+          const phaseReport = {
+            phase: phaseName,
+            total: sumUsage(primary?.[1], fallback?.[1])
           };
+          if (primary) {
+            phaseReport.primary = { modelName: primary[0], ...primary[1] };
+          }
+          if (fallback) {
+            phaseReport.fallback = { modelName: fallback[0], ...fallback[1] };
+          }
+          if (i === 0 && phaseData.metadata.length > 0) {
+            phaseReport.metadata = [...phaseData.metadata];
+          }
+          phases.push(phaseReport);
         }
-        phases.push(phaseReport);
       }
       components.push({
         component: component.component,
@@ -497,8 +511,8 @@ var LLMTokenUsageAggregator = class {
   /**
    * Log comprehensive token usage summary
    *
-   * Outputs usage grouped by component, with phase and model breakdown.
-   * Shows primary and fallback token usage separately for each phase.
+   * Outputs usage grouped by component, with phase and per-model breakdown.
+   * Shows each primary and fallback model on its own line for each phase.
    * Call this once at the end of document processing.
    *
    * @param logger - Logger instance for output
@@ -514,31 +528,23 @@ var LLMTokenUsageAggregator = class {
     let grandInputTokens = 0;
     let grandOutputTokens = 0;
     let grandTotalTokens = 0;
-    let grandPrimaryInputTokens = 0;
-    let grandPrimaryOutputTokens = 0;
-    let grandPrimaryTotalTokens = 0;
-    let grandFallbackInputTokens = 0;
-    let grandFallbackOutputTokens = 0;
-    let grandFallbackTotalTokens = 0;
+    const grandPrimary = emptyUsage();
+    const grandFallback = emptyUsage();
     for (const component of components) {
       logger.info(`${component.component}:`);
-      for (const [phase, phaseData] of Object.entries(component.phases)) {
-        logger.info(`  - ${phase}:`);
-        if (phaseData.primary) {
+      for (const [phaseName, phaseData] of Object.entries(component.phases)) {
+        logger.info(`  - ${phaseName}:`);
+        for (const [modelName, modelUsage] of phaseData.primary) {
           logger.info(
-            `      primary (${phaseData.primary.modelName}): ${formatTokens(phaseData.primary)}`
+            `      primary (${modelName}): ${formatTokens(modelUsage)}`
           );
-          grandPrimaryInputTokens += phaseData.primary.inputTokens;
-          grandPrimaryOutputTokens += phaseData.primary.outputTokens;
-          grandPrimaryTotalTokens += phaseData.primary.totalTokens;
+          addInto(grandPrimary, modelUsage);
         }
-        if (phaseData.fallback) {
+        for (const [modelName, modelUsage] of phaseData.fallback) {
           logger.info(
-            `      fallback (${phaseData.fallback.modelName}): ${formatTokens(phaseData.fallback)}`
+            `      fallback (${modelName}): ${formatTokens(modelUsage)}`
           );
-          grandFallbackInputTokens += phaseData.fallback.inputTokens;
-          grandFallbackOutputTokens += phaseData.fallback.outputTokens;
-          grandFallbackTotalTokens += phaseData.fallback.totalTokens;
+          addInto(grandFallback, modelUsage);
         }
         logger.info(`      subtotal: ${formatTokens(phaseData.total)}`);
       }
@@ -551,23 +557,11 @@ var LLMTokenUsageAggregator = class {
       grandTotalTokens += component.total.totalTokens;
     }
     logger.info("--- Summary ---");
-    if (grandPrimaryTotalTokens > 0) {
-      logger.info(
-        `Primary total: ${formatTokens({
-          inputTokens: grandPrimaryInputTokens,
-          outputTokens: grandPrimaryOutputTokens,
-          totalTokens: grandPrimaryTotalTokens
-        })}`
-      );
+    if (grandPrimary.totalTokens > 0) {
+      logger.info(`Primary total: ${formatTokens(grandPrimary)}`);
     }
-    if (grandFallbackTotalTokens > 0) {
-      logger.info(
-        `Fallback total: ${formatTokens({
-          inputTokens: grandFallbackInputTokens,
-          outputTokens: grandFallbackOutputTokens,
-          totalTokens: grandFallbackTotalTokens
-        })}`
-      );
+    if (grandFallback.totalTokens > 0) {
+      logger.info(`Fallback total: ${formatTokens(grandFallback)}`);
     }
     logger.info(
       `Grand total: ${formatTokens({
@@ -1334,6 +1328,7 @@ var PdfLanguageDetector = class {
         }
       ],
       primaryModel: options.model,
+      fallbackModel: options.fallbackModel,
       maxRetries: options.maxRetries ?? DEFAULT_MAX_RETRIES,
       temperature: options.temperature ?? 0,
       abortSignal: options.abortSignal,
@@ -3302,6 +3297,7 @@ var ReviewAssistancePageGate = class {
         }
       ],
       primaryModel: model,
+      fallbackModel: options.fallbackModel,
       maxRetries: options.maxRetries ?? REVIEW_ASSISTANCE_PAGE_GATE_MAX_RETRIES,
       temperature: options.temperature ?? REVIEW_ASSISTANCE_PAGE_GATE_TEMPERATURE,
       abortSignal: options.abortSignal,
@@ -3573,6 +3569,7 @@ var PostDoclingPageProcessor = class {
           }
         ],
         primaryModel: model,
+        fallbackModel: options?.fallbackModel,
         maxRetries: options?.maxRetries ?? DEFAULT_MAX_RETRIES2,
         temperature: options?.temperature ?? DEFAULT_TEMPERATURE,
         abortSignal: options?.abortSignal,
@@ -3618,6 +3615,7 @@ var PostDoclingPageProcessor = class {
         image,
         gateOptions.model,
         {
+          fallbackModel: gateOptions.fallback,
           maxRetries: gateOptions.maxRetries,
           temperature: gateOptions.temperature,
           abortSignal: options?.abortSignal,
@@ -8863,6 +8861,7 @@ var ReviewAssistanceRunner = class {
             image,
             options.pageGateModel,
             {
+              fallbackModel: options.pageGateFallback,
               maxRetries: options.pageGateMaxRetries,
               temperature: options.pageGateTemperature,
               abortSignal: options.abortSignal,
@@ -9141,7 +9140,7 @@ var ReviewAssistanceRunner = class {
   async reviewWorkItem(context, workItem, image, pageCount, modelResolver, options) {
     const startedAtMs = Date.now();
     const startedAt = new Date(startedAtMs).toISOString();
-    const model = modelResolver(workItem.task);
+    const { model, fallback } = modelResolver(workItem.task);
     const modelId = this.getModelId(model);
     let attempts = 0;
     let validationFeedback = [];
@@ -9182,6 +9181,7 @@ var ReviewAssistanceRunner = class {
               }
             ],
             primaryModel: model,
+            fallbackModel: fallback,
             maxRetries: this.getTaskMaxRetries(workItem.task, options),
             temperature: options.temperature,
             abortSignal: options.abortSignal,
@@ -9968,7 +9968,7 @@ var ReviewAssistanceRunner = class {
    */
   async callMergeArbiter(candidates, context, image, modelResolver, options) {
     const arbiterTask = this.resolveMergeTaskDefinition(candidates);
-    const model = modelResolver(arbiterTask);
+    const { model, fallback } = modelResolver(arbiterTask);
     const conflictRefs = [
       ...new Set(
         candidates.flatMap(
@@ -10007,6 +10007,7 @@ var ReviewAssistanceRunner = class {
           }
         ],
         primaryModel: model,
+        fallbackModel: fallback,
         maxRetries: REVIEW_ASSISTANCE_MERGE_MAX_RETRIES,
         temperature: options.temperature,
         abortSignal: options.abortSignal,
@@ -10559,6 +10560,7 @@ var PostDoclingCorrectionPipeline = class {
         outputDir,
         correction.models.textCorrection,
         {
+          fallbackModel: correction.models.textCorrectionFallback,
           concurrency: correction.concurrency.pages,
           maxRetries: correction.maxRetries.textCorrection,
           temperature: correction.temperature,
@@ -10569,6 +10571,7 @@ var PostDoclingCorrectionPipeline = class {
           pageTexts,
           reviewAssistanceGate: {
             model: correction.models.pageGate,
+            fallback: correction.models.pageGateFallback,
             maxRetries: correction.maxRetries.pageGate,
             temperature: correction.temperature,
             outputLanguage: correction.outputLanguage
@@ -10584,6 +10587,7 @@ var PostDoclingCorrectionPipeline = class {
           pdfPath,
           pageTexts,
           pageGateModel: correction.models.pageGate,
+          pageGateFallback: correction.models.pageGateFallback,
           pageGateMaxRetries: correction.maxRetries.pageGate,
           pageGateTemperature: correction.temperature,
           pageConcurrency: correction.concurrency.pages,
@@ -10609,9 +10613,15 @@ var PostDoclingCorrectionPipeline = class {
   buildReviewAssistanceModelResolver(correction) {
     return (task) => {
       if (task.id === "tables") {
-        return correction.models.tableCorrection ?? correction.models.reviewAssistanceTasks?.tables ?? correction.models.reviewAssistance;
+        return {
+          model: correction.models.tableCorrection ?? correction.models.reviewAssistanceTasks?.tables ?? correction.models.reviewAssistance,
+          fallback: correction.models.tableCorrectionFallback ?? correction.models.reviewAssistanceTasksFallback?.tables ?? correction.models.reviewAssistanceFallback
+        };
       }
-      return correction.models.reviewAssistanceTasks?.[task.id] ?? correction.models.reviewAssistance;
+      return {
+        model: correction.models.reviewAssistanceTasks?.[task.id] ?? correction.models.reviewAssistance,
+        fallback: correction.models.reviewAssistanceTasksFallback?.[task.id] ?? correction.models.reviewAssistanceFallback
+      };
     };
   }
   async extractPageTexts(pdfPath, outputDir) {
@@ -10759,6 +10769,7 @@ var PDFConverter = class {
     try {
       const result = await detector.detect(pdfPath, languageDetectionDir, {
         model: options.languageDetectionModel,
+        fallbackModel: options.languageDetectionFallbackModel,
         aggregator: options.aggregator,
         abortSignal
       });