@claritylabs/cl-sdk 0.18.0 → 1.0.2

package/dist/index.mjs

@@ -38,10 +38,11 @@ async function withRetry(fn, log) {
 
 // src/core/concurrency.ts
 function pLimit(concurrency) {
+  const maxConcurrency = Number.isFinite(concurrency) ? Math.max(1, Math.floor(concurrency)) : 1;
   let active = 0;
   const queue = [];
   function next() {
-    if (queue.length > 0 && active < concurrency) {
+    if (queue.length > 0 && active < maxConcurrency) {
       active++;
       queue.shift()();
     }
@@ -2340,6 +2341,35 @@ async function extractPageRange(input, startPage, endPage) {
   const bytes = await newDoc.save();
   return bytesToBase64(new Uint8Array(bytes));
 }
+async function createPdfPageSlicer(input) {
+  if (isFileIdRef(input)) {
+    throw new Error(
+      "Cannot create a page slicer from a fileId reference. Pass the full PDF as base64/bytes, or provide pre-rendered page assets."
+    );
+  }
+  const srcBytes = await pdfInputToBytes(input);
+  const srcDoc = await PDFDocument.load(srcBytes, { ignoreEncryption: true });
+  const totalPages = srcDoc.getPageCount();
+  const originalBase64 = isBytes(input) ? bytesToBase64(input) : typeof input === "string" ? input : bytesToBase64(srcBytes);
+  return {
+    getPageCount() {
+      return totalPages;
+    },
+    async extractPageRange(startPage, endPage) {
+      const start = Math.max(startPage - 1, 0);
+      const end = Math.min(endPage, totalPages) - 1;
+      if (start === 0 && end >= totalPages - 1) {
+        return originalBase64;
+      }
+      const newDoc = await PDFDocument.create();
+      const indices = Array.from({ length: end - start + 1 }, (_, i) => start + i);
+      const pages = await newDoc.copyPages(srcDoc, indices);
+      pages.forEach((page) => newDoc.addPage(page));
+      const bytes = await newDoc.save();
+      return bytesToBase64(new Uint8Array(bytes));
+    }
+  };
+}
 async function buildPdfProviderOptions(input, existingOptions) {
   const options = { ...existingOptions };
   if (isFileIdRef(input)) {
@@ -2487,20 +2517,19 @@ async function runExtractor(params) {
   } = params;
   const extractorProviderOptions = { ...providerOptions };
   let fullPrompt;
-  const pdfBase64 = await pdfInputToBase64(pdfInput);
+  const needsPdfBase64 = convertPdfToImages && !params.getPageImages || !convertPdfToImages && !params.getPageRangePdf;
+  const pdfBase64 = needsPdfBase64 ? await pdfInputToBase64(pdfInput) : void 0;
   if (convertPdfToImages) {
-    const images = await convertPdfToImages(pdfBase64, startPage, endPage);
+    const images = params.getPageImages ? await params.getPageImages(startPage, endPage) : await convertPdfToImages(pdfBase64, startPage, endPage);
     extractorProviderOptions.images = images;
     fullPrompt = `${prompt}
 
 [Document pages ${startPage}-${endPage} are provided as images.]`;
   } else {
     const cacheKey = `${startPage}-${endPage}`;
-    let pagesPdf = pageRangeCache?.get(cacheKey);
-    if (!pagesPdf) {
-      pagesPdf = await extractPageRange(pdfBase64, startPage, endPage);
-      pageRangeCache?.set(cacheKey, pagesPdf);
-    }
+    const cachedPagesPdf = pageRangeCache?.get(cacheKey);
+    const pagesPdf = cachedPagesPdf ?? (params.getPageRangePdf ? await params.getPageRangePdf(startPage, endPage) : await extractPageRange(pdfBase64, startPage, endPage));
+    if (!cachedPagesPdf) pageRangeCache?.set(cacheKey, pagesPdf);
     extractorProviderOptions.pdfBase64 = pagesPdf;
     fullPrompt = `${prompt}
 
@@ -3486,33 +3515,40 @@ async function formatDocumentContent(doc, generateText, options) {
   for (let i = 0; i < entries.length; i += MAX_ENTRIES_PER_BATCH) {
     batches.push(entries.slice(i, i + MAX_ENTRIES_PER_BATCH));
   }
-  for (let batchIdx = 0; batchIdx < batches.length; batchIdx++) {
-    const batch = batches[batchIdx];
-    try {
-      const prompt = buildFormatPrompt(batch.map((e) => ({ id: e.id, text: e.text })));
-      const result = await withRetry(
-        () => generateText({
-          prompt,
-          maxTokens: options?.maxTokens ?? 16384,
-          providerOptions: options?.providerOptions
-        })
-      );
-      if (result.usage) {
-        totalUsage.inputTokens += result.usage.inputTokens;
-        totalUsage.outputTokens += result.usage.outputTokens;
-      }
-      const formatted = parseFormatResponse(result.text);
-      if (formatted.size < batch.length) {
+  const limit = pLimit(options?.concurrency ?? 2);
+  const batchResults = await Promise.all(batches.map(
+    (batch, batchIdx) => limit(async () => {
+      try {
+        const prompt = buildFormatPrompt(batch.map((e) => ({ id: e.id, text: e.text })));
+        const result = await withRetry(
+          () => generateText({
+            prompt,
+            maxTokens: options?.maxTokens ?? 16384,
+            providerOptions: options?.providerOptions
+          })
+        );
+        const formatted = parseFormatResponse(result.text);
+        if (formatted.size < batch.length) {
+          await options?.log?.(
+            `Format batch ${batchIdx + 1}/${batches.length}: model returned ${formatted.size}/${batch.length} entries \u2014 unformatted entries will keep original content`
+          );
+        }
+        return { batch, formatted, usage: result.usage };
+      } catch (error) {
         await options?.log?.(
-          `Format batch ${batchIdx + 1}/${batches.length}: model returned ${formatted.size}/${batch.length} entries \u2014 unformatted entries will keep original content`
+          `Format batch ${batchIdx + 1}/${batches.length} failed, keeping original content: ${error instanceof Error ? error.message : String(error)}`
         );
+        return void 0;
       }
-      applyFormattedContent(doc, batch, formatted);
-    } catch (error) {
-      await options?.log?.(
-        `Format batch ${batchIdx + 1}/${batches.length} failed, keeping original content: ${error instanceof Error ? error.message : String(error)}`
-      );
+    })
+  ));
+  for (const result of batchResults) {
+    if (!result) continue;
+    if (result.usage) {
+      totalUsage.inputTokens += result.usage.inputTokens;
+      totalUsage.outputTokens += result.usage.outputTokens;
     }
+    applyFormattedContent(doc, result.batch, result.formatted);
   }
   return { document: doc, usage: totalUsage };
 }
@@ -6783,6 +6819,8 @@ async function resolveReferentialCoverages(params) {
     pageCount,
     generateObject,
     convertPdfToImages,
+    getPageRangePdf,
+    getPageImages,
     concurrency = 2,
     providerOptions,
     modelCapabilities,
@@ -6892,6 +6930,8 @@ async function resolveReferentialCoverages(params) {
             endPage: pageRange.endPage,
             generateObject,
             convertPdfToImages,
+            getPageRangePdf,
+            getPageImages,
             maxTokens: budget.maxTokens,
             providerOptions
           });
@@ -6983,6 +7023,8 @@ async function runFocusedExtractorWithFallback(params) {
     convertPdfToImages,
     providerOptions,
     pageRangeCache,
+    getPageRangePdf,
+    getPageImages,
     trackUsage,
     resolveBudget,
     log
@@ -6996,6 +7038,7 @@ async function runFocusedExtractorWithFallback(params) {
     const hintTokens = ext.maxTokens ?? 4096;
     const taskKind = hintTokens >= 8192 ? "extraction_long_list" : "extraction_focused";
     const budget = resolveBudget(taskKind, hintTokens);
+    const startedAt = Date.now();
     const result = await runExtractor({
       name: task.extractorName,
       prompt: ext.buildPrompt(),
@@ -7007,12 +7050,15 @@ async function runFocusedExtractorWithFallback(params) {
       convertPdfToImages,
       maxTokens: budget.maxTokens,
       providerOptions,
-      pageRangeCache
+      pageRangeCache,
+      getPageRangePdf,
+      getPageImages
     });
     trackUsage(result.usage, {
       taskKind,
       label: task.extractorName,
-      maxTokens: budget.maxTokens
+      maxTokens: budget.maxTokens,
+      durationMs: Date.now() - startedAt
     });
     if (!ext.fallback?.isEmpty(result.data)) {
       return result;
@@ -7035,6 +7081,7 @@ async function runFocusedExtractorWithFallback(params) {
     const hintTokens = fallbackExt.maxTokens ?? 4096;
     const taskKind = hintTokens >= 8192 ? "extraction_long_list" : "extraction_focused";
     const budget = resolveBudget(taskKind, hintTokens);
+    const startedAt = Date.now();
     const fallbackResult = await runExtractor({
       name: ext.fallback.extractorName,
       prompt: fallbackExt.buildPrompt(),
@@ -7046,12 +7093,15 @@ async function runFocusedExtractorWithFallback(params) {
       convertPdfToImages,
       maxTokens: budget.maxTokens,
       providerOptions,
-      pageRangeCache
+      pageRangeCache,
+      getPageRangePdf,
+      getPageImages
     });
     trackUsage(fallbackResult.usage, {
       taskKind,
       label: ext.fallback.extractorName,
-      maxTokens: budget.maxTokens
+      maxTokens: budget.maxTokens,
+      durationMs: Date.now() - startedAt
     });
     const focusedData = ext.fallback.deriveFocusedResult(fallbackResult.data);
     return focusedData ? [
@@ -7712,7 +7762,11 @@ function createExtractor(config) {
     generateObject,
     convertPdfToImages,
     concurrency = 2,
+    pageMapConcurrency,
+    extractorConcurrency,
+    formatConcurrency,
     maxReviewRounds = 2,
+    reviewMode = "auto",
     onTokenUsage,
     onProgress,
     log,
@@ -7723,7 +7777,8 @@ function createExtractor(config) {
     modelBudgetConstraints,
     onCheckpointSave
   } = config;
-  const limit = pLimit(concurrency);
+  const pageMapLimit = pLimit(pageMapConcurrency ?? concurrency);
+  const extractorLimit = pLimit(extractorConcurrency ?? concurrency);
   const extractorCatalog = formatExtractorCatalogForPrompt();
   let totalUsage = { inputTokens: 0, outputTokens: 0 };
   let modelCalls = 0;
@@ -7758,7 +7813,7 @@ function createExtractor(config) {
         usage,
         usageReported: !!usage
       });
-      if (report.durationMs) {
+      if (report.durationMs != null) {
         performanceReport.totalModelCallDurationMs += report.durationMs;
       }
     }
@@ -7815,6 +7870,46 @@ function createExtractor(config) {
       return textIncludesSupplementarySignal(JSON.stringify(value));
     });
   }
+  function getSupplementaryPageRanges(pageAssignments, formInventory) {
+    const pages = /* @__PURE__ */ new Set();
+    for (const assignment of pageAssignments) {
+      if (assignment.pageRole === "supplementary" || assignment.extractorNames.includes("supplementary") || textIncludesSupplementarySignal(assignment.notes)) {
+        pages.add(assignment.localPageNumber);
+      }
+    }
+    for (const form of formInventory?.forms ?? []) {
+      if (form.formType === "notice" || textIncludesSupplementarySignal(form.title) || textIncludesSupplementarySignal(form.formNumber)) {
+        const startPage2 = form.pageStart;
+        const endPage = form.pageEnd ?? form.pageStart;
+        if (typeof startPage2 !== "number" || typeof endPage !== "number") continue;
+        for (let page = startPage2; page <= endPage; page += 1) {
+          pages.add(page);
+        }
+      }
+    }
+    const sortedPages = [...pages].sort((a, b) => a - b);
+    if (sortedPages.length === 0) return [];
+    const ranges = [];
+    let startPage = sortedPages[0];
+    let previousPage = sortedPages[0];
+    for (const page of sortedPages.slice(1)) {
+      if (page === previousPage + 1) {
+        previousPage = page;
+        continue;
+      }
+      ranges.push({ startPage, endPage: previousPage });
+      startPage = page;
+      previousPage = page;
+    }
+    ranges.push({ startPage, endPage: previousPage });
+    return ranges;
+  }
+  function shouldRunLlmReview(mode, report, sourceSpansAvailable) {
+    if (mode === "skip" || maxReviewRounds <= 0) return false;
+    if (mode === "always") return true;
+    if (!sourceSpansAvailable) return true;
+    return report.qualityGateStatus !== "passed" || report.issues.length > 0;
+  }
   function buildAlreadyExtractedSummary(memory) {
     const lines = [];
     const declarationResult = readMemoryRecord(memory, "declarations");
@@ -7844,10 +7939,11 @@ function createExtractor(config) {
     }
     return lines.length > 0 ? lines.join("\n") : "";
   }
-  async function runFocusedExtractorTask(task, pdfInput, memory, pageRangeCache) {
+  async function runFocusedExtractorTask(task, pdfInput, memory, pageRangeCache, getPageRangePdf, getPageImages) {
     if (task.extractorName === "supplementary") {
       const alreadyExtractedSummary = buildAlreadyExtractedSummary(memory);
       const budget = resolveBudget("extraction_focused", 4096);
+      const startedAt = Date.now();
       const result = await runExtractor({
         name: "supplementary",
         prompt: buildSupplementaryPrompt(alreadyExtractedSummary),
@@ -7859,12 +7955,15 @@ function createExtractor(config) {
         convertPdfToImages,
         maxTokens: budget.maxTokens,
         providerOptions: activeProviderOptions,
-        pageRangeCache
+        pageRangeCache,
+        getPageRangePdf,
+        getPageImages
       });
       trackUsage(result.usage, {
         taskKind: "extraction_focused",
         label: "supplementary",
-        maxTokens: budget.maxTokens
+        maxTokens: budget.maxTokens,
+        durationMs: Date.now() - startedAt
       });
       return result;
     }
@@ -7875,6 +7974,8 @@ function createExtractor(config) {
       convertPdfToImages,
       providerOptions: activeProviderOptions,
       pageRangeCache,
+      getPageRangePdf,
+      getPageImages,
       trackUsage,
       resolveBudget,
       log
@@ -7923,20 +8024,68 @@ function createExtractor(config) {
       }
     }
     let pdfBase64Cache;
+    const completedPageRangePdfCache = /* @__PURE__ */ new Map();
     const pageRangePdfCache = /* @__PURE__ */ new Map();
+    const pageRangeImageCache = /* @__PURE__ */ new Map();
+    let pdfSlicerPromise;
+    let fullPdfProviderOptionsPromise;
+    let pageCountPromise;
     async function getPdfBase64ForExtraction() {
       if (pdfBase64Cache === void 0) {
         pdfBase64Cache = await pdfInputToBase64(pdfInput);
       }
       return pdfBase64Cache;
     }
+    async function getCachedPageCount() {
+      if (!pageCountPromise) {
+        pageCountPromise = getPdfSlicer().then((slicer) => slicer.getPageCount()).catch(() => getPdfPageCount(pdfInput));
+      }
+      return pageCountPromise;
+    }
+    async function getFullPdfProviderOptions() {
+      if (!fullPdfProviderOptionsPromise) {
+        fullPdfProviderOptionsPromise = buildPdfProviderOptions(pdfInput, activeProviderOptions);
+      }
+      return fullPdfProviderOptionsPromise;
+    }
+    async function getPdfSlicer() {
+      if (!pdfSlicerPromise) {
+        pdfSlicerPromise = createPdfPageSlicer(pdfInput);
+      }
+      return pdfSlicerPromise;
+    }
     async function getPageRangePdf(startPage, endPage) {
       const cacheKey = `${startPage}-${endPage}`;
-      const cached = pageRangePdfCache.get(cacheKey);
+      const cached = completedPageRangePdfCache.get(cacheKey);
+      if (cached) return cached;
+      const pending = pageRangePdfCache.get(cacheKey);
+      if (pending) return pending;
+      const promise = (async () => {
+        const slicer = await getPdfSlicer();
+        const pagesPdf = await slicer.extractPageRange(startPage, endPage);
+        completedPageRangePdfCache.set(cacheKey, pagesPdf);
+        return pagesPdf;
+      })().catch((error) => {
+        pageRangePdfCache.delete(cacheKey);
+        throw error;
+      });
+      pageRangePdfCache.set(cacheKey, promise);
+      return promise;
+    }
+    async function getPageImages(startPage, endPage) {
+      if (!convertPdfToImages) return [];
+      const cacheKey = `${startPage}-${endPage}`;
+      const cached = pageRangeImageCache.get(cacheKey);
       if (cached) return cached;
-      const pagesPdf = await extractPageRange(await getPdfBase64ForExtraction(), startPage, endPage);
-      pageRangePdfCache.set(cacheKey, pagesPdf);
-      return pagesPdf;
+      const promise = (async () => {
+        const pdfBase64 = await getPdfBase64ForExtraction();
+        return convertPdfToImages(pdfBase64, startPage, endPage);
+      })().catch((error) => {
+        pageRangeImageCache.delete(cacheKey);
+        throw error;
+      });
+      pageRangeImageCache.set(cacheKey, promise);
+      return promise;
     }
     let classifyResult;
     if (resumed?.classifyResult && pipelineCtx.isPhaseComplete("classify")) {
@@ -7944,15 +8093,16 @@ function createExtractor(config) {
       onProgress?.("Resuming from checkpoint (classify complete)...");
     } else {
       onProgress?.("Classifying document...");
-      const pageCount2 = await getPdfPageCount(pdfInput);
+      const pageCount2 = await getCachedPageCount();
       const budget = resolveBudget("extraction_classify", 512);
+      const startedAt = Date.now();
       const classifyResponse = await safeGenerateObject(
         generateObject,
         {
           prompt: buildClassifyPrompt(),
           schema: ClassifyResultSchema,
           maxTokens: budget.maxTokens,
-          providerOptions: await buildPdfProviderOptions(pdfInput, activeProviderOptions)
+          providerOptions: await getFullPdfProviderOptions()
         },
         {
           fallback: { documentType: "policy", policyTypes: ["other"], confidence: 0 },
@@ -7964,7 +8114,8 @@ function createExtractor(config) {
       trackUsage(classifyResponse.usage, {
         taskKind: "extraction_classify",
         label: "classify",
-        maxTokens: budget.maxTokens
+        maxTokens: budget.maxTokens,
+        durationMs: Date.now() - startedAt
       });
       classifyResult = classifyResponse.object;
       if (classifyResult.confidence === 0) {
@@ -7982,7 +8133,7 @@ function createExtractor(config) {
     const policyTypes = classifyResult.policyTypes ?? [];
     const primaryType = policyTypes[0] ?? "other";
     const template = getTemplate(primaryType);
-    const pageCount = resumed?.pageCount ?? await getPdfPageCount(pdfInput);
+    const pageCount = resumed?.pageCount ?? await getCachedPageCount();
     const templateHints = buildTemplateHints(primaryType, documentType, pageCount, template);
     let formInventory;
     if (resumed?.formInventory && pipelineCtx.isPhaseComplete("form_inventory")) {
@@ -7992,13 +8143,14 @@ function createExtractor(config) {
     } else {
       onProgress?.(`Building form inventory for ${primaryType} ${documentType}...`);
       const budget = resolveBudget("extraction_form_inventory", 2048);
+      const startedAt = Date.now();
       const formInventoryResponse = await safeGenerateObject(
         generateObject,
         {
           prompt: buildFormInventoryPrompt(templateHints),
           schema: FormInventorySchema,
           maxTokens: budget.maxTokens,
-          providerOptions: await buildPdfProviderOptions(pdfInput, activeProviderOptions)
+          providerOptions: await getFullPdfProviderOptions()
         },
         {
           fallback: { forms: [] },
@@ -8009,7 +8161,8 @@ function createExtractor(config) {
       trackUsage(formInventoryResponse.usage, {
         taskKind: "extraction_form_inventory",
         label: "form_inventory",
-        maxTokens: budget.maxTokens
+        maxTokens: budget.maxTokens,
+        durationMs: Date.now() - startedAt
       });
       formInventory = formInventoryResponse.object;
       memory.set("form_inventory", formInventory);
@@ -8039,9 +8192,10 @@ function createExtractor(config) {
       );
       const pageMapResults = await Promise.all(
         pageMapChunks.map(
-          ({ startPage, endPage }) => limit(async () => {
+          ({ startPage, endPage }) => pageMapLimit(async () => {
             const pagesPdf = await getPageRangePdf(startPage, endPage);
             const budget = resolveBudget("extraction_page_map", 2048);
+            const startedAt = Date.now();
             const mapResponse = await safeGenerateObject(
               generateObject,
               {
@@ -8066,7 +8220,8 @@ function createExtractor(config) {
             trackUsage(mapResponse.usage, {
               taskKind: "extraction_page_map",
               label: `page_map:${startPage}-${endPage}`,
-              maxTokens: budget.maxTokens
+              maxTokens: budget.maxTokens,
+              durationMs: Date.now() - startedAt
             });
             return mapResponse.object.pages.map((assignment) => ({
               ...assignment,
@@ -8112,14 +8267,32 @@ function createExtractor(config) {
       });
     }
     if (!pipelineCtx.isPhaseComplete("extract")) {
-      const tasks = plan.tasks;
+      const supplementaryRanges = getSupplementaryPageRanges(pageAssignments, formInventory);
+      const baseTasks = plan.tasks;
+      const hasPlannedSupplementary = baseTasks.some((task) => task.extractorName === "supplementary");
+      const tasks = hasPlannedSupplementary || supplementaryRanges.length === 0 ? baseTasks : [
+        ...baseTasks,
+        ...supplementaryRanges.map((range) => ({
+          extractorName: "supplementary",
+          startPage: range.startPage,
+          endPage: range.endPage,
+          description: `Page-signaled supplementary extraction for pages ${range.startPage}-${range.endPage}`
+        }))
+      ];
       onProgress?.(`Dispatching ${tasks.length} extractors...`);
       const extractionPdfInput = await getPdfBase64ForExtraction();
       const extractorResults = await Promise.all(
         tasks.map(
-          (task) => limit(async () => {
+          (task) => extractorLimit(async () => {
             onProgress?.(`Extracting ${task.extractorName} (pages ${task.startPage}-${task.endPage})...`);
-            return runFocusedExtractorTask(task, extractionPdfInput, memory, pageRangePdfCache);
+            return runFocusedExtractorTask(
+              task,
+              extractionPdfInput,
+              memory,
+              completedPageRangePdfCache,
+              getPageRangePdf,
+              convertPdfToImages ? getPageImages : void 0
+            );
           })
         )
       );
@@ -8134,6 +8307,7 @@ function createExtractor(config) {
         try {
           const alreadyExtractedSummary = buildAlreadyExtractedSummary(memory);
           const budget = resolveBudget("extraction_focused", 4096);
+          const startedAt = Date.now();
           const supplementaryResult = await runExtractor({
             name: "supplementary",
             prompt: buildSupplementaryPrompt(alreadyExtractedSummary),
@@ -8145,12 +8319,15 @@ function createExtractor(config) {
             convertPdfToImages,
             maxTokens: budget.maxTokens,
             providerOptions: activeProviderOptions,
-            pageRangeCache: pageRangePdfCache
+            pageRangeCache: completedPageRangePdfCache,
+            getPageRangePdf,
+            getPageImages: convertPdfToImages ? getPageImages : void 0
           });
           trackUsage(supplementaryResult.usage, {
             taskKind: "extraction_focused",
             label: "supplementary",
-            maxTokens: budget.maxTokens
+            maxTokens: budget.maxTokens,
+            durationMs: Date.now() - startedAt
           });
           mergeMemoryResult(supplementaryResult.name, supplementaryResult.data, memory);
         } catch (error) {
@@ -8170,6 +8347,7 @@ function createExtractor(config) {
     if (!pipelineCtx.isPhaseComplete("resolve_referential")) {
       onProgress?.("Resolving referential coverage limits...");
       try {
+        const startedAt = Date.now();
         const resolution = await resolveReferentialCoverages({
           memory,
           pdfInput,
@@ -8177,6 +8355,8 @@ function createExtractor(config) {
           generateObject,
           convertPdfToImages,
           concurrency,
+          getPageRangePdf,
+          getPageImages: convertPdfToImages ? getPageImages : void 0,
           providerOptions: activeProviderOptions,
           modelCapabilities,
           modelBudgetConstraints,
@@ -8185,7 +8365,8 @@ function createExtractor(config) {
         });
         trackUsage(resolution.usage, {
           taskKind: "extraction_referential_lookup",
-          label: "referential_resolution"
+          label: "referential_resolution",
+          durationMs: Date.now() - startedAt
         });
         if (resolution.attempts > 0) {
           await log?.(`Referential resolution: ${resolution.resolved}/${resolution.attempts} resolved, ${resolution.unresolved} unresolved`);
@@ -8207,52 +8388,72 @@ function createExtractor(config) {
     let reviewReport = resumed?.reviewReport;
     if (!pipelineCtx.isPhaseComplete("review")) {
       reviewRounds = [];
-      for (let round = 0; round < maxReviewRounds; round++) {
-        const extractedKeys = [...memory.keys()].filter((k) => k !== "classify");
-        const extractionSummary = summarizeExtraction(memory);
-        const pageMapSummary = formatPageMapSummary(pageAssignments);
-        const budget = resolveBudget("extraction_review", 1536);
-        const reviewResponse = await safeGenerateObject(
-          generateObject,
-          {
-            prompt: buildReviewPrompt(template.required, extractedKeys, extractionSummary, pageMapSummary, extractorCatalog),
-            schema: ReviewResultSchema,
+      groundExtractionMemoryWithSourceSpans(memory, sourceSpans);
+      const preReviewReport = buildExtractionReviewReport({
+        memory,
+        pageAssignments,
+        reviewRounds,
+        sourceSpansAvailable: sourceSpans.length > 0
+      });
+      if (shouldRunLlmReview(reviewMode, preReviewReport, sourceSpans.length > 0)) {
+        for (let round = 0; round < maxReviewRounds; round++) {
+          const extractedKeys = [...memory.keys()].filter((k) => k !== "classify");
+          const extractionSummary = summarizeExtraction(memory);
+          const pageMapSummary = formatPageMapSummary(pageAssignments);
+          const budget = resolveBudget("extraction_review", 1536);
+          const startedAt = Date.now();
+          const reviewResponse = await safeGenerateObject(
+            generateObject,
+            {
+              prompt: buildReviewPrompt(template.required, extractedKeys, extractionSummary, pageMapSummary, extractorCatalog),
+              schema: ReviewResultSchema,
+              maxTokens: budget.maxTokens,
+              providerOptions: await getFullPdfProviderOptions()
+            },
+            {
+              fallback: { complete: true, missingFields: [], qualityIssues: [], additionalTasks: [] },
+              log,
+              onError: (err, attempt) => log?.(`Review round ${round + 1} attempt ${attempt + 1} failed: ${err}`)
+            }
+          );
+          trackUsage(reviewResponse.usage, {
+            taskKind: "extraction_review",
+            label: `review:${round + 1}`,
             maxTokens: budget.maxTokens,
-            providerOptions: await buildPdfProviderOptions(pdfInput, activeProviderOptions)
-          },
-          {
-            fallback: { complete: true, missingFields: [], qualityIssues: [], additionalTasks: [] },
-            log,
-            onError: (err, attempt) => log?.(`Review round ${round + 1} attempt ${attempt + 1} failed: ${err}`)
+            durationMs: Date.now() - startedAt
+          });
+          reviewRounds.push(toReviewRoundRecord(round + 1, reviewResponse.object));
+          if (reviewResponse.object.qualityIssues?.length) {
+            await log?.(`Review round ${round + 1} quality issues: ${reviewResponse.object.qualityIssues.join("; ")}`);
           }
-        );
-        trackUsage(reviewResponse.usage, {
-          taskKind: "extraction_review",
-          label: `review:${round + 1}`,
-          maxTokens: budget.maxTokens
-        });
-        reviewRounds.push(toReviewRoundRecord(round + 1, reviewResponse.object));
-        if (reviewResponse.object.qualityIssues?.length) {
-          await log?.(`Review round ${round + 1} quality issues: ${reviewResponse.object.qualityIssues.join("; ")}`);
-        }
-        if (reviewResponse.object.complete || reviewResponse.object.additionalTasks.length === 0) {
-          onProgress?.("Extraction complete.");
-          break;
-        }
-        onProgress?.(`Review round ${round + 1}: dispatching ${reviewResponse.object.additionalTasks.length} follow-up extractors...`);
-        const extractionPdfInput = await getPdfBase64ForExtraction();
-        const followUpResults = await Promise.all(
-          reviewResponse.object.additionalTasks.map(
-            (task) => limit(async () => {
-              return runFocusedExtractorTask(task, extractionPdfInput, memory, pageRangePdfCache);
-            })
-          )
-        );
-        for (const result of followUpResults.flatMap((item) => Array.isArray(item) ? item : item ? [item] : [])) {
-          if (result) {
-            mergeMemoryResult(result.name, result.data, memory);
+          if (reviewResponse.object.complete || reviewResponse.object.additionalTasks.length === 0) {
+            onProgress?.("Extraction complete.");
+            break;
+          }
+          onProgress?.(`Review round ${round + 1}: dispatching ${reviewResponse.object.additionalTasks.length} follow-up extractors...`);
+          const extractionPdfInput = await getPdfBase64ForExtraction();
+          const followUpResults = await Promise.all(
+            reviewResponse.object.additionalTasks.map(
+              (task) => extractorLimit(async () => {
+                return runFocusedExtractorTask(
+                  task,
+                  extractionPdfInput,
+                  memory,
+                  completedPageRangePdfCache,
+                  getPageRangePdf,
+                  convertPdfToImages ? getPageImages : void 0
+                );
+              })
+            )
+          );
+          for (const result of followUpResults.flatMap((item) => Array.isArray(item) ? item : item ? [item] : [])) {
+            if (result) {
+              mergeMemoryResult(result.name, result.data, memory);
+            }
           }
         }
+      } else {
+        onProgress?.("Skipping LLM extraction review; deterministic checks passed.");
       }
       groundExtractionMemoryWithSourceSpans(memory, sourceSpans);
       reviewReport = buildExtractionReviewReport({
@@ -8304,6 +8505,7 @@ function createExtractor(config) {
       onProgress?.("Generating document summary...");
       try {
         const budget = resolveBudget("extraction_summary", 512);
+        const startedAt = Date.now();
         const summaryResponse = await safeGenerateObject(
           generateObject,
           {
@@ -8321,7 +8523,8 @@ function createExtractor(config) {
         trackUsage(summaryResponse.usage, {
           taskKind: "extraction_summary",
           label: "summary",
-          maxTokens: budget.maxTokens
+          maxTokens: budget.maxTokens,
+          durationMs: Date.now() - startedAt
         });
         if (summaryResponse.object.summary) {
           document.summary = summaryResponse.object.summary;
@@ -8332,16 +8535,19 @@ function createExtractor(config) {
     }
     onProgress?.("Formatting extracted content...");
     const formatBudget = resolveBudget("extraction_format", 16384);
+    const formatStartedAt = Date.now();
     const formatResult = await formatDocumentContent(document, generateText, {
       providerOptions: activeProviderOptions,
       maxTokens: formatBudget.maxTokens,
+      concurrency: formatConcurrency ?? concurrency,
       onProgress,
       log
     });
     trackUsage(formatResult.usage, {
       taskKind: "extraction_format",
       label: "format",
-      maxTokens: formatBudget.maxTokens
+      maxTokens: formatBudget.maxTokens,
+      durationMs: Date.now() - formatStartedAt
     });
     const chunks = chunkDocument(formatResult.document);
     const finalCheckpoint = pipelineCtx.getCheckpoint();