@claritylabs/cl-sdk 1.0.0 → 1.1.4

package/README.md

@@ -99,7 +99,7 @@ A multi-pass system that turns insurance PDFs into structured, queryable data:
 
 - **Pass 0 — Classification**: Determines whether a document is a policy or a quote. Returns document type, confidence score, and supporting signals.
 - **Pass 1 — Metadata Extraction**: Extracts high-level metadata — carrier, policy/quote number, dates, premium, insured name, coverage table with limits and deductibles. Includes an early persistence callback (`onMetadata`) so metadata is saved immediately, surviving downstream failures.
-- **Pass 2 — Section Extraction**: Splits the document into page chunks (starting at 15 pages) and extracts structured sections. Adaptive fallback: if a chunk's output is truncated (JSON parse failure), it re-splits into smaller chunks (10, then 5 pages), and escalates to the fallback model. Results are merged across chunks.
+- **Pass 2 — Section Extraction**: Splits the document into page chunks (starting at 15 pages) and extracts structured sections in parallel (concurrency-limited, default 2). All model calls automatically retry on rate-limit errors with exponential backoff. Adaptive fallback: if a chunk's output is truncated (JSON parse failure), it re-splits into smaller chunks (10, then 5 pages), and escalates to the fallback model. Results are merged across chunks.
 - **Pass 3 — Enrichment**: A non-fatal pass that parses raw text into structured supplementary fields — regulatory context, complaint contacts, costs and fees, claims contacts.
 
 For quotes specifically, the pipeline also extracts premium breakdowns, subjectivities (conditions that must be met before binding), and underwriting conditions.
@@ -160,12 +160,52 @@ interface ExtractOptions {
   models?: ModelConfig;
   metadataProviderOptions?: ProviderOptions;
   fallbackProviderOptions?: ProviderOptions;
+  concurrency?: number;          // parallel chunk limit (default: 2)
+  onTokenUsage?: (usage: TokenUsage) => void;
+}
+
+interface ExtractSectionsOptions {
+  log?: LogFn;
+  promptBuilder?: PromptBuilder;
+  models?: ModelConfig;
+  fallbackProviderOptions?: ProviderOptions;
+  concurrency?: number;          // parallel chunk limit (default: 2)
+  onTokenUsage?: (usage: TokenUsage) => void;
 }
 
 interface ClassifyOptions {
   log?: LogFn;
   models?: ModelConfig;
+  onTokenUsage?: (usage: TokenUsage) => void;
 }
+
+interface TokenUsage {
+  inputTokens: number;
+  outputTokens: number;
+}
+```
+
+### Rate-Limit Resilience
+
+All model calls automatically retry on rate-limit errors (HTTP 429 or "rate limit" in error message) with exponential backoff — up to 5 retries with delays of 2s, 4s, 8s, 16s, 32s (plus jitter). Non-rate-limit errors are re-thrown immediately.
+
+### Parallel Chunk Extraction
+
+Pass 2 section extraction processes page chunks in parallel with a configurable concurrency limit (default: 2). This balances throughput against rate limits. Sub-chunk retries on truncation are also parallelized.
+
+```typescript
+// Track token usage across all passes
+let totalInput = 0, totalOutput = 0;
+
+const { extracted } = await extractFromPdf(pdfBase64, {
+  concurrency: 3,
+  onTokenUsage: ({ inputTokens, outputTokens }) => {
+    totalInput += inputTokens;
+    totalOutput += outputTokens;
+  },
+});
+
+console.log(`Total: ${totalInput} input, ${totalOutput} output tokens`);
 ```
 
 ### Agent

package/dist/index.d.mts

@@ -407,10 +407,12 @@ declare function getPageChunks(totalPages: number, chunkSize?: number): Array<[n
  * Pass 3: Enrich supplementary fields with structured data.
  * Text-only enrichment call — non-fatal on failure (returns document unchanged).
  */
-declare function enrichSupplementaryFields(document: any, models?: ModelConfig, log?: LogFn): Promise<any>;
+declare function enrichSupplementaryFields(document: any, models?: ModelConfig, log?: LogFn, onTokenUsage?: (usage: TokenUsage) => void): Promise<any>;
 interface ClassifyOptions {
     log?: LogFn;
     models?: ModelConfig;
+    /** Called after each model call with token usage for tracking. */
+    onTokenUsage?: (usage: TokenUsage) => void;
 }
 /**
  * Pass 0: Classify document as policy or quote.
@@ -454,6 +456,11 @@ declare function applyExtractedQuote(extracted: any): {
  */
 declare function mergeChunkedQuoteSections(metadataResult: any, sectionChunks: any[]): any;
 type PromptBuilder = (pageStart: number, pageEnd: number) => string;
+/** Token usage reported per model call. */
+interface TokenUsage {
+    inputTokens: number;
+    outputTokens: number;
+}
 interface ExtractOptions {
     log?: LogFn;
     onMetadata?: (raw: string) => Promise<void>;
@@ -462,6 +469,10 @@ interface ExtractOptions {
     metadataProviderOptions?: ProviderOptions;
     /** Provider-specific options for fallback calls. Defaults to Anthropic thinking enabled. */
     fallbackProviderOptions?: ProviderOptions;
+    /** Maximum number of chunk extractions to run in parallel (default: 2). */
+    concurrency?: number;
+    /** Called after each model call with token usage for tracking. */
+    onTokenUsage?: (usage: TokenUsage) => void;
 }
 /**
  * Full extraction pipeline for policy documents (passes 1-3).
@@ -483,6 +494,10 @@ interface ExtractSectionsOptions {
     models?: ModelConfig;
     /** Provider-specific options for fallback calls. */
     fallbackProviderOptions?: ProviderOptions;
+    /** Maximum number of chunk extractions to run in parallel (default: 2). */
+    concurrency?: number;
+    /** Called after each model call with token usage for tracking. */
+    onTokenUsage?: (usage: TokenUsage) => void;
 }
 /**
  * Sections-only extraction: skip pass 1, use saved metadata.
@@ -533,4 +548,4 @@ interface TextOverlay {
 /** Overlay text on a flat PDF at specified coordinates. */
 declare function overlayTextOnPdf(pdfBytes: Uint8Array, overlays: TextOverlay[]): Promise<Uint8Array>;
 
-export { AGENT_TOOLS, APPLICATION_CLASSIFY_PROMPT, type AcroFormFieldInfo, type AgentContext, type BaseDocument, CLASSIFY_DOCUMENT_PROMPT, CLASSIFY_EMAIL_PROMPT, COI_GENERATION_TOOL, COVERAGE_COMPARISON_TOOL, type ClassifyOptions, type CommunicationIntent, type Coverage, DOCUMENT_LOOKUP_TOOL, EXTRACTION_PROMPT, type ExtractOptions, type ExtractSectionsOptions, type FieldMapping, HAIKU_MODEL, type InsuranceDocument, type LogFn, METADATA_PROMPT, MODEL_TOKEN_LIMITS, type ModelConfig, PLATFORM_CONFIGS, type Platform, type PlatformConfig, type PolicyDocument, type PremiumLine, type PromptBuilder, QUOTE_METADATA_PROMPT, type QuoteDocument, SONNET_MODEL, type Section, type Subjectivity, type Subsection, type TextOverlay, type ToolDefinition, type UnderwritingCondition, applyExtracted, applyExtractedQuote, buildAcroFormMappingPrompt, buildAgentSystemPrompt, buildAnswerParsingPrompt, buildAutoFillPrompt, buildBatchEmailGenerationPrompt, buildClassifyMessagePrompt, buildCoiRoutingPrompt, buildConfirmationSummaryPrompt, buildConversationMemoryContext, buildConversationMemoryGuidance, buildCoverageGapPrompt, buildDocumentContext, buildFieldExplanationPrompt, buildFieldExtractionPrompt, buildFlatPdfMappingPrompt, buildFormattingPrompt, buildIdentityPrompt, buildIntentPrompt, buildLookupFillPrompt, buildPolicyContext, buildPolicySectionsPrompt, buildQuestionBatchPrompt, buildQuoteSectionsPrompt, buildQuotesPoliciesPrompt, buildReplyIntentClassificationPrompt, buildSafetyPrompt, buildSectionsPrompt, buildSupplementaryEnrichmentPrompt, buildSystemPrompt, classifyDocumentType, createDefaultModelConfig, createUniformModelConfig, enrichSupplementaryFields, extractFromPdf, extractQuoteFromPdf, extractSectionsOnly, fillAcroForm, getAcroFormFields, getPageChunks, mergeChunkedQuoteSections, mergeChunkedSections, overlayTextOnPdf, sanitizeNulls, stripFences };
+export { AGENT_TOOLS, APPLICATION_CLASSIFY_PROMPT, type AcroFormFieldInfo, type AgentContext, type BaseDocument, CLASSIFY_DOCUMENT_PROMPT, CLASSIFY_EMAIL_PROMPT, COI_GENERATION_TOOL, COVERAGE_COMPARISON_TOOL, type ClassifyOptions, type CommunicationIntent, type Coverage, DOCUMENT_LOOKUP_TOOL, EXTRACTION_PROMPT, type ExtractOptions, type ExtractSectionsOptions, type FieldMapping, HAIKU_MODEL, type InsuranceDocument, type LogFn, METADATA_PROMPT, MODEL_TOKEN_LIMITS, type ModelConfig, PLATFORM_CONFIGS, type Platform, type PlatformConfig, type PolicyDocument, type PremiumLine, type PromptBuilder, QUOTE_METADATA_PROMPT, type QuoteDocument, SONNET_MODEL, type Section, type Subjectivity, type Subsection, type TextOverlay, type TokenUsage, type ToolDefinition, type UnderwritingCondition, applyExtracted, applyExtractedQuote, buildAcroFormMappingPrompt, buildAgentSystemPrompt, buildAnswerParsingPrompt, buildAutoFillPrompt, buildBatchEmailGenerationPrompt, buildClassifyMessagePrompt, buildCoiRoutingPrompt, buildConfirmationSummaryPrompt, buildConversationMemoryContext, buildConversationMemoryGuidance, buildCoverageGapPrompt, buildDocumentContext, buildFieldExplanationPrompt, buildFieldExtractionPrompt, buildFlatPdfMappingPrompt, buildFormattingPrompt, buildIdentityPrompt, buildIntentPrompt, buildLookupFillPrompt, buildPolicyContext, buildPolicySectionsPrompt, buildQuestionBatchPrompt, buildQuoteSectionsPrompt, buildQuotesPoliciesPrompt, buildReplyIntentClassificationPrompt, buildSafetyPrompt, buildSectionsPrompt, buildSupplementaryEnrichmentPrompt, buildSystemPrompt, classifyDocumentType, createDefaultModelConfig, createUniformModelConfig, enrichSupplementaryFields, extractFromPdf, extractQuoteFromPdf, extractSectionsOnly, fillAcroForm, getAcroFormFields, getPageChunks, mergeChunkedQuoteSections, mergeChunkedSections, overlayTextOnPdf, sanitizeNulls, stripFences };

package/dist/index.d.ts

@@ -407,10 +407,12 @@ declare function getPageChunks(totalPages: number, chunkSize?: number): Array<[n
  * Pass 3: Enrich supplementary fields with structured data.
  * Text-only enrichment call — non-fatal on failure (returns document unchanged).
  */
-declare function enrichSupplementaryFields(document: any, models?: ModelConfig, log?: LogFn): Promise<any>;
+declare function enrichSupplementaryFields(document: any, models?: ModelConfig, log?: LogFn, onTokenUsage?: (usage: TokenUsage) => void): Promise<any>;
 interface ClassifyOptions {
     log?: LogFn;
     models?: ModelConfig;
+    /** Called after each model call with token usage for tracking. */
+    onTokenUsage?: (usage: TokenUsage) => void;
 }
 /**
  * Pass 0: Classify document as policy or quote.
@@ -454,6 +456,11 @@ declare function applyExtractedQuote(extracted: any): {
  */
 declare function mergeChunkedQuoteSections(metadataResult: any, sectionChunks: any[]): any;
 type PromptBuilder = (pageStart: number, pageEnd: number) => string;
+/** Token usage reported per model call. */
+interface TokenUsage {
+    inputTokens: number;
+    outputTokens: number;
+}
 interface ExtractOptions {
     log?: LogFn;
     onMetadata?: (raw: string) => Promise<void>;
@@ -462,6 +469,10 @@ interface ExtractOptions {
     metadataProviderOptions?: ProviderOptions;
     /** Provider-specific options for fallback calls. Defaults to Anthropic thinking enabled. */
     fallbackProviderOptions?: ProviderOptions;
+    /** Maximum number of chunk extractions to run in parallel (default: 2). */
+    concurrency?: number;
+    /** Called after each model call with token usage for tracking. */
+    onTokenUsage?: (usage: TokenUsage) => void;
 }
 /**
  * Full extraction pipeline for policy documents (passes 1-3).
@@ -483,6 +494,10 @@ interface ExtractSectionsOptions {
     models?: ModelConfig;
     /** Provider-specific options for fallback calls. */
     fallbackProviderOptions?: ProviderOptions;
+    /** Maximum number of chunk extractions to run in parallel (default: 2). */
+    concurrency?: number;
+    /** Called after each model call with token usage for tracking. */
+    onTokenUsage?: (usage: TokenUsage) => void;
 }
 /**
  * Sections-only extraction: skip pass 1, use saved metadata.
@@ -533,4 +548,4 @@ interface TextOverlay {
 /** Overlay text on a flat PDF at specified coordinates. */
 declare function overlayTextOnPdf(pdfBytes: Uint8Array, overlays: TextOverlay[]): Promise<Uint8Array>;
 
-export { AGENT_TOOLS, APPLICATION_CLASSIFY_PROMPT, type AcroFormFieldInfo, type AgentContext, type BaseDocument, CLASSIFY_DOCUMENT_PROMPT, CLASSIFY_EMAIL_PROMPT, COI_GENERATION_TOOL, COVERAGE_COMPARISON_TOOL, type ClassifyOptions, type CommunicationIntent, type Coverage, DOCUMENT_LOOKUP_TOOL, EXTRACTION_PROMPT, type ExtractOptions, type ExtractSectionsOptions, type FieldMapping, HAIKU_MODEL, type InsuranceDocument, type LogFn, METADATA_PROMPT, MODEL_TOKEN_LIMITS, type ModelConfig, PLATFORM_CONFIGS, type Platform, type PlatformConfig, type PolicyDocument, type PremiumLine, type PromptBuilder, QUOTE_METADATA_PROMPT, type QuoteDocument, SONNET_MODEL, type Section, type Subjectivity, type Subsection, type TextOverlay, type ToolDefinition, type UnderwritingCondition, applyExtracted, applyExtractedQuote, buildAcroFormMappingPrompt, buildAgentSystemPrompt, buildAnswerParsingPrompt, buildAutoFillPrompt, buildBatchEmailGenerationPrompt, buildClassifyMessagePrompt, buildCoiRoutingPrompt, buildConfirmationSummaryPrompt, buildConversationMemoryContext, buildConversationMemoryGuidance, buildCoverageGapPrompt, buildDocumentContext, buildFieldExplanationPrompt, buildFieldExtractionPrompt, buildFlatPdfMappingPrompt, buildFormattingPrompt, buildIdentityPrompt, buildIntentPrompt, buildLookupFillPrompt, buildPolicyContext, buildPolicySectionsPrompt, buildQuestionBatchPrompt, buildQuoteSectionsPrompt, buildQuotesPoliciesPrompt, buildReplyIntentClassificationPrompt, buildSafetyPrompt, buildSectionsPrompt, buildSupplementaryEnrichmentPrompt, buildSystemPrompt, classifyDocumentType, createDefaultModelConfig, createUniformModelConfig, enrichSupplementaryFields, extractFromPdf, extractQuoteFromPdf, extractSectionsOnly, fillAcroForm, getAcroFormFields, getPageChunks, mergeChunkedQuoteSections, mergeChunkedSections, overlayTextOnPdf, sanitizeNulls, stripFences };
+export { AGENT_TOOLS, APPLICATION_CLASSIFY_PROMPT, type AcroFormFieldInfo, type AgentContext, type BaseDocument, CLASSIFY_DOCUMENT_PROMPT, CLASSIFY_EMAIL_PROMPT, COI_GENERATION_TOOL, COVERAGE_COMPARISON_TOOL, type ClassifyOptions, type CommunicationIntent, type Coverage, DOCUMENT_LOOKUP_TOOL, EXTRACTION_PROMPT, type ExtractOptions, type ExtractSectionsOptions, type FieldMapping, HAIKU_MODEL, type InsuranceDocument, type LogFn, METADATA_PROMPT, MODEL_TOKEN_LIMITS, type ModelConfig, PLATFORM_CONFIGS, type Platform, type PlatformConfig, type PolicyDocument, type PremiumLine, type PromptBuilder, QUOTE_METADATA_PROMPT, type QuoteDocument, SONNET_MODEL, type Section, type Subjectivity, type Subsection, type TextOverlay, type TokenUsage, type ToolDefinition, type UnderwritingCondition, applyExtracted, applyExtractedQuote, buildAcroFormMappingPrompt, buildAgentSystemPrompt, buildAnswerParsingPrompt, buildAutoFillPrompt, buildBatchEmailGenerationPrompt, buildClassifyMessagePrompt, buildCoiRoutingPrompt, buildConfirmationSummaryPrompt, buildConversationMemoryContext, buildConversationMemoryGuidance, buildCoverageGapPrompt, buildDocumentContext, buildFieldExplanationPrompt, buildFieldExtractionPrompt, buildFlatPdfMappingPrompt, buildFormattingPrompt, buildIdentityPrompt, buildIntentPrompt, buildLookupFillPrompt, buildPolicyContext, buildPolicySectionsPrompt, buildQuestionBatchPrompt, buildQuoteSectionsPrompt, buildQuotesPoliciesPrompt, buildReplyIntentClassificationPrompt, buildSafetyPrompt, buildSectionsPrompt, buildSupplementaryEnrichmentPrompt, buildSystemPrompt, classifyDocumentType, createDefaultModelConfig, createUniformModelConfig, enrichSupplementaryFields, extractFromPdf, extractQuoteFromPdf, extractSectionsOnly, fillAcroForm, getAcroFormFields, getPageChunks, mergeChunkedQuoteSections, mergeChunkedSections, overlayTextOnPdf, sanitizeNulls, stripFences };

package/dist/index.js

@@ -29870,6 +29870,56 @@ var DEFAULT_METADATA_PROVIDER_OPTIONS = {
 var DEFAULT_FALLBACK_PROVIDER_OPTIONS = {
   anthropic: { thinking: { type: "enabled", budgetTokens: 4096 } }
 };
+var MAX_RETRIES = 5;
+var BASE_DELAY_MS = 2e3;
+function isRateLimitError(error) {
+  if (error instanceof Error) {
+    const msg = error.message.toLowerCase();
+    if (msg.includes("rate limit") || msg.includes("rate_limit") || msg.includes("too many requests")) {
+      return true;
+    }
+  }
+  if (typeof error === "object" && error !== null) {
+    const status = error.status ?? error.statusCode;
+    if (status === 429) return true;
+  }
+  return false;
+}
+async function withRetry(fn, log) {
+  for (let attempt = 0; ; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      if (!isRateLimitError(error) || attempt >= MAX_RETRIES) {
+        throw error;
+      }
+      const jitter = Math.random() * 1e3;
+      const delay = BASE_DELAY_MS * Math.pow(2, attempt) + jitter;
+      await log?.(`Rate limited, retrying in ${(delay / 1e3).toFixed(1)}s (attempt ${attempt + 1}/${MAX_RETRIES})...`);
+      await new Promise((resolve) => setTimeout(resolve, delay));
+    }
+  }
+}
+function pLimit(concurrency) {
+  let active = 0;
+  const queue = [];
+  function next() {
+    if (queue.length > 0 && active < concurrency) {
+      active++;
+      queue.shift()();
+    }
+  }
+  return (fn) => new Promise((resolve, reject) => {
+    const run = () => {
+      fn().then(resolve, reject).finally(() => {
+        active--;
+        next();
+      });
+    };
+    queue.push(run);
+    next();
+  });
+}
 function stripFences(text) {
   return text.replace(/^```(?:json)?\s*\n?/i, "").replace(/\n?```\s*$/i, "");
 }
@@ -29948,48 +29998,56 @@ function getPageChunks(totalPages, chunkSize = 30) {
   }
   return chunks;
 }
-async function callModel(model, pdfBase64, prompt, maxTokens, providerOptions, log) {
+async function callModel(model, pdfBase64, prompt, maxTokens, providerOptions, log, onTokenUsage) {
   await log?.(`Calling model (max ${maxTokens} tokens)...`);
   const start = Date.now();
-  const { text, usage } = await (0, import_ai.generateText)({
-    model,
-    maxOutputTokens: maxTokens,
-    messages: [{
-      role: "user",
-      content: [
-        { type: "file", data: pdfBase64, mediaType: "application/pdf" },
-        { type: "text", text: prompt }
-      ]
-    }],
-    ...providerOptions ? { providerOptions } : {}
-  });
+  const { text, usage } = await withRetry(
+    () => (0, import_ai.generateText)({
+      model,
+      maxOutputTokens: maxTokens,
+      messages: [{
+        role: "user",
+        content: [
+          { type: "file", data: pdfBase64, mediaType: "application/pdf" },
+          { type: "text", text: prompt }
+        ]
+      }],
+      ...providerOptions ? { providerOptions } : {}
+    }),
+    log
+  );
   const elapsed = ((Date.now() - start) / 1e3).toFixed(1);
   const inputTokens = usage?.inputTokens ?? 0;
   const outputTokens = usage?.outputTokens ?? 0;
   await log?.(`${inputTokens} in / ${outputTokens} out tokens (${elapsed}s)`);
+  onTokenUsage?.({ inputTokens, outputTokens });
   return text || "{}";
 }
-async function callModelText(model, prompt, maxTokens, log) {
+async function callModelText(model, prompt, maxTokens, log, onTokenUsage) {
   await log?.(`Calling model text-only (max ${maxTokens} tokens)...`);
   const start = Date.now();
-  const { text, usage } = await (0, import_ai.generateText)({
-    model,
-    maxOutputTokens: maxTokens,
-    messages: [{
-      role: "user",
-      content: prompt
-    }]
-  });
+  const { text, usage } = await withRetry(
+    () => (0, import_ai.generateText)({
+      model,
+      maxOutputTokens: maxTokens,
+      messages: [{
+        role: "user",
+        content: prompt
+      }]
+    }),
+    log
+  );
   const elapsed = ((Date.now() - start) / 1e3).toFixed(1);
   const inputTokens = usage?.inputTokens ?? 0;
   const outputTokens = usage?.outputTokens ?? 0;
   await log?.(`text: ${inputTokens} in / ${outputTokens} out tokens (${elapsed}s)`);
+  onTokenUsage?.({ inputTokens, outputTokens });
   return text || "{}";
 }
 function resolveModels(models) {
   return models ?? createDefaultModelConfig();
 }
-async function enrichSupplementaryFields(document, models, log) {
+async function enrichSupplementaryFields(document, models, log, onTokenUsage) {
   const fields = {};
   if (document.regulatoryContext?.content) {
     fields.regulatoryContext = document.regulatoryContext.content;
@@ -30011,7 +30069,7 @@ async function enrichSupplementaryFields(document, models, log) {
   try {
     const resolved = resolveModels(models);
     const prompt = buildSupplementaryEnrichmentPrompt(fields);
-    const raw = await callModelText(resolved.enrichment, prompt, MODEL_TOKEN_LIMITS.enrichment, log);
+    const raw = await callModelText(resolved.enrichment, prompt, MODEL_TOKEN_LIMITS.enrichment, log, onTokenUsage);
     const parsed = JSON.parse(stripFences(raw));
     const enriched = { ...document };
     if (parsed.regulatoryContext && enriched.regulatoryContext) {
@@ -30046,7 +30104,7 @@ async function enrichSupplementaryFields(document, models, log) {
   }
 }
 async function classifyDocumentType(pdfBase64, options) {
-  const { log, models } = options ?? {};
+  const { log, models, onTokenUsage } = options ?? {};
   const resolved = resolveModels(models);
   await log?.("Pass 0: Classifying document type...");
   const raw = await callModel(
@@ -30055,7 +30113,8 @@ async function classifyDocumentType(pdfBase64, options) {
     CLASSIFY_DOCUMENT_PROMPT,
     MODEL_TOKEN_LIMITS.classification,
     void 0,
-    log
+    log,
+    onTokenUsage
   );
   try {
     const parsed = JSON.parse(stripFences(raw));
@@ -30135,7 +30194,7 @@ function mergeChunkedQuoteSections(metadataResult, sectionChunks) {
   };
 }
 var CHUNK_SIZES = [15, 10, 5];
-async function extractChunkWithRetry(models, pdfBase64, start, end, sizeIndex, promptBuilder, fallbackProviderOptions, log) {
+async function extractChunkWithRetry(models, pdfBase64, start, end, sizeIndex, promptBuilder, fallbackProviderOptions, log, onTokenUsage, concurrency = 2) {
   await log?.(`Pass 2: Extracting sections pages ${start}\u2013${end}...`);
   const chunkRaw = await callModel(
     models.sections,
@@ -30143,7 +30202,8 @@ async function extractChunkWithRetry(models, pdfBase64, start, end, sizeIndex, p
     promptBuilder(start, end),
     MODEL_TOKEN_LIMITS.sections,
     void 0,
-    log
+    log,
+    onTokenUsage
   );
   try {
     return [JSON.parse(stripFences(chunkRaw))];
@@ -30157,21 +30217,24 @@ async function extractChunkWithRetry(models, pdfBase64, start, end, sizeIndex, p
         const subChunks = getPageChunks(pageSpan, smallerSize).map(
           ([s, e]) => [s + start - 1, e + start - 1]
         );
-        const results = [];
-        for (const [subStart, subEnd] of subChunks) {
-          const subResults = await extractChunkWithRetry(
-            models,
-            pdfBase64,
-            subStart,
-            subEnd,
-            nextSizeIndex,
-            promptBuilder,
-            fallbackProviderOptions,
-            log
-          );
-          results.push(...subResults);
-        }
-        return results;
+        const limit = pLimit(concurrency);
+        const nestedResults = await Promise.all(
+          subChunks.map(
+            ([subStart, subEnd]) => limit(() => extractChunkWithRetry(
+              models,
+              pdfBase64,
+              subStart,
+              subEnd,
+              nextSizeIndex,
+              promptBuilder,
+              fallbackProviderOptions,
+              log,
+              onTokenUsage,
+              concurrency
+            ))
+          )
+        );
+        return nestedResults.flat();
       }
     }
     await log?.(`Sections model exhausted for pages ${start}\u2013${end}, falling back...`);
@@ -30181,7 +30244,8 @@ async function extractChunkWithRetry(models, pdfBase64, start, end, sizeIndex, p
       promptBuilder(start, end),
       MODEL_TOKEN_LIMITS.sectionsFallback,
       fallbackProviderOptions,
-      log
+      log,
+      onTokenUsage
     );
     try {
       return [JSON.parse(stripFences(fallbackRaw))];
@@ -30192,23 +30256,26 @@ async function extractChunkWithRetry(models, pdfBase64, start, end, sizeIndex, p
     }
   }
 }
-async function extractSectionChunks(models, pdfBase64, pageCount, promptBuilder = buildSectionsPrompt, fallbackProviderOptions, log) {
+async function extractSectionChunks(models, pdfBase64, pageCount, promptBuilder = buildSectionsPrompt, fallbackProviderOptions, log, onTokenUsage, concurrency = 2) {
   const chunks = getPageChunks(pageCount, CHUNK_SIZES[0]);
-  const sectionChunks = [];
-  for (const [start, end] of chunks) {
-    const results = await extractChunkWithRetry(
-      models,
-      pdfBase64,
-      start,
-      end,
-      0,
-      promptBuilder,
-      fallbackProviderOptions,
-      log
-    );
-    sectionChunks.push(...results);
-  }
-  return sectionChunks;
+  const limit = pLimit(concurrency);
+  const nestedResults = await Promise.all(
+    chunks.map(
+      ([start, end]) => limit(() => extractChunkWithRetry(
+        models,
+        pdfBase64,
+        start,
+        end,
+        0,
+        promptBuilder,
+        fallbackProviderOptions,
+        log,
+        onTokenUsage,
+        concurrency
+      ))
+    )
+  );
+  return nestedResults.flat();
 }
 async function extractFromPdf(pdfBase64, options) {
   const {
@@ -30216,7 +30283,9 @@ async function extractFromPdf(pdfBase64, options) {
     onMetadata,
     models,
     metadataProviderOptions = DEFAULT_METADATA_PROVIDER_OPTIONS,
-    fallbackProviderOptions = DEFAULT_FALLBACK_PROVIDER_OPTIONS
+    fallbackProviderOptions = DEFAULT_FALLBACK_PROVIDER_OPTIONS,
+    concurrency = 2,
+    onTokenUsage
   } = options ?? {};
   const resolved = resolveModels(models);
   await log?.("Pass 1: Extracting metadata...");
@@ -30226,7 +30295,8 @@ async function extractFromPdf(pdfBase64, options) {
     METADATA_PROMPT,
     MODEL_TOKEN_LIMITS.metadata,
     metadataProviderOptions,
-    log
+    log,
+    onTokenUsage
   );
   let metadataResult;
   try {
@@ -30245,12 +30315,14 @@ async function extractFromPdf(pdfBase64, options) {
     pageCount,
     buildSectionsPrompt,
     fallbackProviderOptions,
-    log
+    log,
+    onTokenUsage,
+    concurrency
   );
   await log?.("Merging extraction results...");
   const merged = mergeChunkedSections(metadataResult, sectionChunks);
   if (merged.document) {
-    merged.document = await enrichSupplementaryFields(merged.document, resolved, log);
+    merged.document = await enrichSupplementaryFields(merged.document, resolved, log, onTokenUsage);
   }
   const mergedRaw = JSON.stringify(merged);
   return { rawText: mergedRaw, extracted: merged };
@@ -30260,7 +30332,9 @@ async function extractSectionsOnly(pdfBase64, metadataRaw, options) {
     log,
     promptBuilder = buildSectionsPrompt,
     models,
-    fallbackProviderOptions = DEFAULT_FALLBACK_PROVIDER_OPTIONS
+    fallbackProviderOptions = DEFAULT_FALLBACK_PROVIDER_OPTIONS,
+    concurrency = 2,
+    onTokenUsage
   } = options ?? {};
   const resolved = resolveModels(models);
   await log?.("Using saved metadata, skipping pass 1...");
@@ -30278,12 +30352,14 @@ async function extractSectionsOnly(pdfBase64, metadataRaw, options) {
     pageCount,
     promptBuilder,
     fallbackProviderOptions,
-    log
+    log,
+    onTokenUsage,
+    concurrency
   );
   await log?.("Merging extraction results...");
   const merged = mergeChunkedSections(metadataResult, sectionChunks);
   if (merged.document) {
-    merged.document = await enrichSupplementaryFields(merged.document, resolved, log);
+    merged.document = await enrichSupplementaryFields(merged.document, resolved, log, onTokenUsage);
   }
   const mergedRaw = JSON.stringify(merged);
   return { rawText: mergedRaw, extracted: merged };
@@ -30294,7 +30370,9 @@ async function extractQuoteFromPdf(pdfBase64, options) {
     onMetadata,
     models,
     metadataProviderOptions = DEFAULT_METADATA_PROVIDER_OPTIONS,
-    fallbackProviderOptions = DEFAULT_FALLBACK_PROVIDER_OPTIONS
+    fallbackProviderOptions = DEFAULT_FALLBACK_PROVIDER_OPTIONS,
+    concurrency = 2,
+    onTokenUsage
   } = options ?? {};
   const resolved = resolveModels(models);
   await log?.("Pass 1: Extracting quote metadata...");
@@ -30304,7 +30382,8 @@ async function extractQuoteFromPdf(pdfBase64, options) {
     QUOTE_METADATA_PROMPT,
     MODEL_TOKEN_LIMITS.metadata,
     metadataProviderOptions,
-    log
+    log,
+    onTokenUsage
   );
   let metadataResult;
   try {
@@ -30323,7 +30402,9 @@ async function extractQuoteFromPdf(pdfBase64, options) {
     pageCount,
     buildQuoteSectionsPrompt,
     fallbackProviderOptions,
-    log
+    log,
+    onTokenUsage,
+    concurrency
   );
   await log?.("Merging quote extraction results...");
   const merged = mergeChunkedQuoteSections(metadataResult, sectionChunks);