@claritylabs/cl-sdk 1.0.2 → 1.1.0

package/dist/index.mjs

@@ -1496,7 +1496,7 @@ var CaseEvidenceSourceSchema = z18.object({
   page: z18.number().optional(),
   fieldPath: z18.string().optional(),
   text: z18.string().describe("Source text available for span validation and citation"),
-  metadata: z18.record(z18.string()).optional()
+  metadata: z18.record(z18.string(), z18.string()).optional()
 });
 var CaseCitationSchema = z18.object({
   sourceId: z18.string(),
@@ -1873,7 +1873,7 @@ var SourceSpanSchema = z20.object({
   formNumber: z20.string().optional(),
   bbox: z20.array(SourceSpanBBoxSchema).optional(),
   location: SourceSpanLocationSchema.optional(),
-  metadata: z20.record(z20.string()).optional()
+  metadata: z20.record(z20.string(), z20.string()).optional()
 });
 var SourceSpanRefSchema = z20.object({
   sourceSpanId: z20.string().min(1),
@@ -1891,7 +1891,7 @@ var SourceChunkSchema = z20.object({
   textHash: z20.string().min(1),
   pageStart: z20.number().int().positive().optional(),
   pageEnd: z20.number().int().positive().optional(),
-  metadata: z20.record(z20.string()).default({})
+  metadata: z20.record(z20.string(), z20.string()).default({})
 });
 
 // src/source/ids.ts
@@ -2512,6 +2512,8 @@ async function runExtractor(params) {
     generateObject,
     convertPdfToImages,
     maxTokens = 4096,
+    taskKind,
+    budgetDiagnostics,
     providerOptions,
     pageRangeCache
   } = params;
@@ -2545,6 +2547,8 @@ async function runExtractor(params) {
       prompt: fullPrompt,
       schema: strictSchema,
       maxTokens,
+      taskKind,
+      budgetDiagnostics,
       providerOptions: extractorProviderOptions
     })
   );
@@ -3524,6 +3528,8 @@ async function formatDocumentContent(doc, generateText, options) {
           () => generateText({
             prompt,
             maxTokens: options?.maxTokens ?? 16384,
+            taskKind: options?.taskKind,
+            budgetDiagnostics: options?.budgetDiagnostics,
             providerOptions: options?.providerOptions
           })
         );
@@ -6787,6 +6793,8 @@ If you cannot find the section, return startPage: 0 and endPage: 0.
 Return JSON only.`,
         schema: PageLocationSchema,
         maxTokens: budget.maxTokens,
+        taskKind: "extraction_referential_lookup",
+        budgetDiagnostics: budget,
         providerOptions: await buildPdfProviderOptions(pdfInput, providerOptions)
       },
       {
@@ -6933,6 +6941,8 @@ async function resolveReferentialCoverages(params) {
             getPageRangePdf,
             getPageImages,
             maxTokens: budget.maxTokens,
+            taskKind: "extraction_referential_lookup",
+            budgetDiagnostics: budget,
             providerOptions
           });
           trackUsage(result.usage);
@@ -7049,6 +7059,8 @@ async function runFocusedExtractorWithFallback(params) {
       generateObject,
       convertPdfToImages,
       maxTokens: budget.maxTokens,
+      taskKind,
+      budgetDiagnostics: budget,
       providerOptions,
       pageRangeCache,
       getPageRangePdf,
@@ -7092,6 +7104,8 @@ async function runFocusedExtractorWithFallback(params) {
       generateObject,
       convertPdfToImages,
       maxTokens: budget.maxTokens,
+      taskKind,
+      budgetDiagnostics: budget,
       providerOptions,
       pageRangeCache,
       getPageRangePdf,
@@ -7954,6 +7968,8 @@ function createExtractor(config) {
         generateObject,
         convertPdfToImages,
         maxTokens: budget.maxTokens,
+        taskKind: "extraction_focused",
+        budgetDiagnostics: budget,
         providerOptions: activeProviderOptions,
         pageRangeCache,
         getPageRangePdf,
@@ -8102,6 +8118,8 @@ function createExtractor(config) {
           prompt: buildClassifyPrompt(),
           schema: ClassifyResultSchema,
           maxTokens: budget.maxTokens,
+          taskKind: "extraction_classify",
+          budgetDiagnostics: budget,
           providerOptions: await getFullPdfProviderOptions()
         },
         {
@@ -8150,6 +8168,8 @@ function createExtractor(config) {
           prompt: buildFormInventoryPrompt(templateHints),
           schema: FormInventorySchema,
           maxTokens: budget.maxTokens,
+          taskKind: "extraction_form_inventory",
+          budgetDiagnostics: budget,
           providerOptions: await getFullPdfProviderOptions()
         },
         {
@@ -8202,6 +8222,8 @@ function createExtractor(config) {
                 prompt: buildPageMapPrompt(templateHints, startPage, endPage, formInventoryHint),
                 schema: PageMapChunkSchema,
                 maxTokens: budget.maxTokens,
+                taskKind: "extraction_page_map",
+                budgetDiagnostics: budget,
                 providerOptions: { ...activeProviderOptions, pdfBase64: pagesPdf }
               },
               {
@@ -8318,6 +8340,8 @@ function createExtractor(config) {
             generateObject,
             convertPdfToImages,
             maxTokens: budget.maxTokens,
+            taskKind: "extraction_focused",
+            budgetDiagnostics: budget,
             providerOptions: activeProviderOptions,
             pageRangeCache: completedPageRangePdfCache,
             getPageRangePdf,
@@ -8408,10 +8432,19 @@ function createExtractor(config) {
               prompt: buildReviewPrompt(template.required, extractedKeys, extractionSummary, pageMapSummary, extractorCatalog),
               schema: ReviewResultSchema,
               maxTokens: budget.maxTokens,
+              taskKind: "extraction_review",
+              budgetDiagnostics: budget,
               providerOptions: await getFullPdfProviderOptions()
             },
             {
-              fallback: { complete: true, missingFields: [], qualityIssues: [], additionalTasks: [] },
+              fallback: {
+                complete: false,
+                missingFields: ["llm_review_unavailable"],
+                qualityIssues: [
+                  "LLM extraction review failed; deterministic review was used and the result needs review."
+                ],
+                additionalTasks: []
+              },
               log,
               onError: (err, attempt) => log?.(`Review round ${round + 1} attempt ${attempt + 1} failed: ${err}`)
             }
@@ -8512,6 +8545,8 @@ function createExtractor(config) {
             prompt: buildSummaryPrompt(document),
             schema: SummaryResultSchema,
             maxTokens: budget.maxTokens,
+            taskKind: "extraction_summary",
+            budgetDiagnostics: budget,
             providerOptions: activeProviderOptions
           },
           {
@@ -8539,6 +8574,8 @@ function createExtractor(config) {
     const formatResult = await formatDocumentContent(document, generateText, {
       providerOptions: activeProviderOptions,
       maxTokens: formatBudget.maxTokens,
+      taskKind: "extraction_format",
+      budgetDiagnostics: formatBudget,
       concurrency: formatConcurrency ?? concurrency,
       onProgress,
       log
@@ -8941,6 +8978,7 @@ async function classifyApplication(pdfContent, generateObject, providerOptions,
 Analyze the attached insurance document. If text source units are provided in provider options, use them as supporting context. Do not infer from base64 text.`,
       schema: ApplicationClassifyResultSchema,
       maxTokens,
+      taskKind: "application_classify",
       providerOptions: {
         ...providerOptions,
         pdfBase64: providerOptions?.pdfBase64 ?? pdfContent
@@ -9043,6 +9081,7 @@ Extract fields from the attached application PDF. Use provider-supplied source u
       prompt,
       schema: FieldExtractionResultSchema,
       maxTokens,
+      taskKind: "application_extract_fields",
       providerOptions: {
         ...providerOptions,
         pdfBase64: providerOptions?.pdfBase64 ?? pdfContent
@@ -9096,6 +9135,7 @@ async function autoFillFromContext(fields, orgContext, generateObject, providerO
       prompt,
       schema: AutoFillResultSchema,
       maxTokens,
+      taskKind: "application_auto_fill",
       providerOptions
     })
   );
@@ -9166,6 +9206,7 @@ async function batchQuestions(unfilledFields, generateObject, providerOptions, m
       prompt,
       schema: QuestionBatchResultSchema,
       maxTokens,
+      taskKind: "application_batch",
       providerOptions
     })
   );
@@ -9217,6 +9258,7 @@ async function classifyReplyIntent(fields, replyText, generateObject, providerOp
       prompt,
       schema: ReplyIntentSchema,
       maxTokens,
+      taskKind: "application_classify",
       providerOptions
     })
   );
@@ -9276,6 +9318,7 @@ async function parseAnswers(fields, replyText, generateObject, providerOptions,
       prompt,
       schema: AnswerParsingResultSchema,
       maxTokens,
+      taskKind: "application_parse_answers",
       providerOptions
     })
   );
@@ -9405,6 +9448,7 @@ async function fillFromLookup(requests, targetFields, availableData, generateObj
       prompt,
       schema: LookupFillResultSchema,
       maxTokens,
+      taskKind: "application_lookup",
       providerOptions
     })
   );
@@ -9487,6 +9531,7 @@ async function generateBatchEmail(batchFields, batchIndex, totalBatches, opts, g
     () => generateText({
       prompt,
       maxTokens,
+      taskKind: "application_email",
       providerOptions
     })
   );
@@ -10009,11 +10054,14 @@ function createApplicationPipeline(config) {
     }
     if (replyPlan.answerQuestion && intent.questionText) {
       try {
+        const budget = resolveBudget("application_email", 512);
         const { text, usage } = await generateText({
           prompt: `The user is filling out an insurance application and asked: "${intent.questionText}"
 
 Provide a brief, helpful explanation (2-3 sentences). End with "Just reply with the answer when you're ready and I'll fill it in."`,
-          maxTokens: resolveBudget("application_email", 512).maxTokens,
+          maxTokens: budget.maxTokens,
+          taskKind: "application_email",
+          budgetDiagnostics: budget,
           providerOptions
         });
         trackUsage(usage);
@@ -10138,6 +10186,7 @@ ${emailText}`;
     if (!state) throw new Error(`Application ${applicationId} not found`);
     const filledFields = state.fields.filter((f) => f.value);
     const fieldSummary = filledFields.map((f) => `${f.section} > ${f.label}: ${f.value} (source: ${f.source ?? "unknown"})`).join("\n");
+    const budget = resolveBudget("application_email", 4096);
     const { text, usage } = await generateText({
       prompt: `Format these filled insurance application fields as a clean confirmation summary for the user to review. Group by section, show each field as "Label: Value". End with a note asking them to confirm or request changes.
 
@@ -10145,7 +10194,9 @@ Application: ${state.title ?? "Insurance Application"}
 
 Fields:
 ${fieldSummary}`,
-      maxTokens: resolveBudget("application_email", 4096).maxTokens,
+      maxTokens: budget.maxTokens,
+      taskKind: "application_email",
+      budgetDiagnostics: budget,
       providerOptions
     });
     trackUsage(usage);
@@ -10619,6 +10670,8 @@ ${e.text}`;
       prompt,
       schema: SubAnswerSchema,
       maxTokens: budget.maxTokens,
+      taskKind: "query_reason",
+      budgetDiagnostics: budget,
       providerOptions
     })
   );
@@ -10842,6 +10895,8 @@ async function verify(originalQuestion, subAnswers, allEvidence, config) {
       prompt,
       schema: VerifyResultSchema,
       maxTokens: budget.maxTokens,
+      taskKind: "query_verify",
+      budgetDiagnostics: budget,
       providerOptions
     })
   );
@@ -10984,6 +11039,8 @@ async function interpretAttachments(params) {
         prompt,
         schema: AttachmentInterpretationSchema,
         maxTokens: budget.maxTokens,
+        taskKind: "query_attachment",
+        budgetDiagnostics: budget,
         providerOptions: buildAttachmentProviderOptions(attachment, providerOptions)
       },
       {
@@ -11321,6 +11378,8 @@ function createQueryAgent(config) {
         prompt,
         schema: QueryClassifyResultSchema,
         maxTokens: budget.maxTokens,
+        taskKind: "query_classify",
+        budgetDiagnostics: budget,
         providerOptions
       },
       {
@@ -11372,6 +11431,8 @@ function createQueryAgent(config) {
         prompt,
         schema: QueryResultSchema,
         maxTokens: budget.maxTokens,
+        taskKind: "query_respond",
+        budgetDiagnostics: budget,
         providerOptions
       },
       {
@@ -11467,6 +11528,8 @@ function createPceAgent(config = {}) {
           prompt: buildPceNormalizePrompt({ requestText: input.requestText, evidenceSources }),
           schema: PceNormalizationResultSchema,
           maxTokens: budget.maxTokens,
+          taskKind: "pce_impact_analysis",
+          budgetDiagnostics: budget,
           providerOptions: config.providerOptions
         },
         { fallback, maxRetries: 1, log: config.log }
@@ -11528,6 +11591,8 @@ function createPceAgent(config = {}) {
           }),
           schema: ReplyAnswersSchema,
           maxTokens: budget.maxTokens,
+          taskKind: "pce_reply_parse",
+          budgetDiagnostics: budget,
           providerOptions: config.providerOptions
         },
         { fallback: { answers }, maxRetries: 1, log: config.log }