@claritylabs/cl-sdk 1.0.2 → 1.1.0

package/README.md

@@ -27,13 +27,13 @@ npm install @claritylabs/cl-sdk pdf-lib zod
 import { createExtractor } from "@claritylabs/cl-sdk";
 
 const extractor = createExtractor({
-  generateText: async ({ prompt, system, maxTokens, providerOptions }) => {
-    const result = await yourProvider.generate({ prompt, system, maxTokens, providerOptions });
+  generateText: async ({ prompt, system, maxTokens, taskKind, budgetDiagnostics, providerOptions }) => {
+    const result = await yourProvider.generate({ prompt, system, maxTokens, taskKind, budgetDiagnostics, providerOptions });
     return { text: result.text, usage: result.usage };
   },
-  generateObject: async ({ prompt, system, schema, maxTokens, providerOptions }) => {
+  generateObject: async ({ prompt, system, schema, maxTokens, taskKind, budgetDiagnostics, providerOptions }) => {
     // Pass providerOptions.pdfBase64 and/or providerOptions.images to your model
-    const result = await yourProvider.generateStructured({ prompt, system, schema, maxTokens, providerOptions });
+    const result = await yourProvider.generateStructured({ prompt, system, schema, maxTokens, taskKind, budgetDiagnostics, providerOptions });
     return { object: result.object, usage: result.usage };
   },
   concurrency: 3,
@@ -120,6 +120,10 @@ Important: your `generateObject` callback must actually forward multimodal paylo
 
 If your callback ignores those fields, the model will only see the text prompt.
 
+## Model routing metadata
+
+Every SDK model callback may receive `taskKind` and `budgetDiagnostics`. Hosts can use these provider-agnostic fields for cheap-first routing, fallback, and telemetry without the SDK hardcoding model names. Example task kinds include `extraction_classify`, `extraction_focused`, `extraction_review`, `query_reason`, `application_extract_fields`, and `pce_impact_analysis`. `budgetDiagnostics` includes the resolved max-token budget and truncation-risk warnings for the current subtask.
+
 ## Bounded Agentic Workflows
 
 CL-SDK uses deterministic scaffolding with agentic decision points rather than fixed all-tools-all-the-time chains:

package/dist/index.d.mts

@@ -68,6 +68,10 @@ type GenerateText = (params: {
     prompt: string;
     system?: string;
     maxTokens: number;
+    /** Provider-agnostic subtask label for host-side model routing, fallback, and telemetry. */
+    taskKind?: ModelTaskKind;
+    /** Resolved budget diagnostics for hosts that route/escalate based on truncation risk. */
+    budgetDiagnostics?: ModelBudgetResolution;
     providerOptions?: Record<string, unknown>;
 }) => Promise<{
     text: string;
@@ -96,6 +100,10 @@ type GenerateObject<T = unknown> = (params: {
     system?: string;
     schema: ZodSchema<T>;
     maxTokens: number;
+    /** Provider-agnostic subtask label for host-side model routing, fallback, and telemetry. */
+    taskKind?: ModelTaskKind;
+    /** Resolved budget diagnostics for hosts that route/escalate based on truncation risk. */
+    budgetDiagnostics?: ModelBudgetResolution;
     providerOptions?: Record<string, unknown>;
 }) => Promise<{
     object: T;
@@ -160,6 +168,8 @@ interface SafeGenerateParams {
     prompt: string;
     system?: string;
     maxTokens: number;
+    taskKind?: ModelTaskKind;
+    budgetDiagnostics?: ModelBudgetResolution;
     providerOptions?: Record<string, unknown>;
 }
 /**

package/dist/index.d.ts

@@ -68,6 +68,10 @@ type GenerateText = (params: {
     prompt: string;
     system?: string;
     maxTokens: number;
+    /** Provider-agnostic subtask label for host-side model routing, fallback, and telemetry. */
+    taskKind?: ModelTaskKind;
+    /** Resolved budget diagnostics for hosts that route/escalate based on truncation risk. */
+    budgetDiagnostics?: ModelBudgetResolution;
     providerOptions?: Record<string, unknown>;
 }) => Promise<{
     text: string;
@@ -96,6 +100,10 @@ type GenerateObject<T = unknown> = (params: {
     system?: string;
     schema: ZodSchema<T>;
     maxTokens: number;
+    /** Provider-agnostic subtask label for host-side model routing, fallback, and telemetry. */
+    taskKind?: ModelTaskKind;
+    /** Resolved budget diagnostics for hosts that route/escalate based on truncation risk. */
+    budgetDiagnostics?: ModelBudgetResolution;
     providerOptions?: Record<string, unknown>;
 }) => Promise<{
     object: T;
@@ -160,6 +168,8 @@ interface SafeGenerateParams {
     prompt: string;
     system?: string;
     maxTokens: number;
+    taskKind?: ModelTaskKind;
+    budgetDiagnostics?: ModelBudgetResolution;
     providerOptions?: Record<string, unknown>;
 }
 /**

package/dist/index.js

@@ -1827,7 +1827,7 @@ var CaseEvidenceSourceSchema = import_zod18.z.object({
   page: import_zod18.z.number().optional(),
   fieldPath: import_zod18.z.string().optional(),
   text: import_zod18.z.string().describe("Source text available for span validation and citation"),
-  metadata: import_zod18.z.record(import_zod18.z.string()).optional()
+  metadata: import_zod18.z.record(import_zod18.z.string(), import_zod18.z.string()).optional()
 });
 var CaseCitationSchema = import_zod18.z.object({
   sourceId: import_zod18.z.string(),
@@ -2204,7 +2204,7 @@ var SourceSpanSchema = import_zod20.z.object({
   formNumber: import_zod20.z.string().optional(),
   bbox: import_zod20.z.array(SourceSpanBBoxSchema).optional(),
   location: SourceSpanLocationSchema.optional(),
-  metadata: import_zod20.z.record(import_zod20.z.string()).optional()
+  metadata: import_zod20.z.record(import_zod20.z.string(), import_zod20.z.string()).optional()
 });
 var SourceSpanRefSchema = import_zod20.z.object({
   sourceSpanId: import_zod20.z.string().min(1),
@@ -2222,7 +2222,7 @@ var SourceChunkSchema = import_zod20.z.object({
   textHash: import_zod20.z.string().min(1),
   pageStart: import_zod20.z.number().int().positive().optional(),
   pageEnd: import_zod20.z.number().int().positive().optional(),
-  metadata: import_zod20.z.record(import_zod20.z.string()).default({})
+  metadata: import_zod20.z.record(import_zod20.z.string(), import_zod20.z.string()).default({})
 });
 
 // src/source/ids.ts
@@ -2835,6 +2835,8 @@ async function runExtractor(params) {
     generateObject,
     convertPdfToImages,
     maxTokens = 4096,
+    taskKind,
+    budgetDiagnostics,
     providerOptions,
     pageRangeCache
   } = params;
@@ -2868,6 +2870,8 @@ async function runExtractor(params) {
       prompt: fullPrompt,
       schema: strictSchema,
       maxTokens,
+      taskKind,
+      budgetDiagnostics,
       providerOptions: extractorProviderOptions
     })
   );
@@ -3847,6 +3851,8 @@ async function formatDocumentContent(doc, generateText, options) {
           () => generateText({
             prompt,
             maxTokens: options?.maxTokens ?? 16384,
+            taskKind: options?.taskKind,
+            budgetDiagnostics: options?.budgetDiagnostics,
             providerOptions: options?.providerOptions
           })
         );
@@ -7110,6 +7116,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)
       },
       {
@@ -7256,6 +7264,8 @@ async function resolveReferentialCoverages(params) {
             getPageRangePdf,
             getPageImages,
             maxTokens: budget.maxTokens,
+            taskKind: "extraction_referential_lookup",
+            budgetDiagnostics: budget,
             providerOptions
           });
           trackUsage(result.usage);
@@ -7372,6 +7382,8 @@ async function runFocusedExtractorWithFallback(params) {
       generateObject,
       convertPdfToImages,
       maxTokens: budget.maxTokens,
+      taskKind,
+      budgetDiagnostics: budget,
       providerOptions,
       pageRangeCache,
       getPageRangePdf,
@@ -7415,6 +7427,8 @@ async function runFocusedExtractorWithFallback(params) {
       generateObject,
       convertPdfToImages,
       maxTokens: budget.maxTokens,
+      taskKind,
+      budgetDiagnostics: budget,
       providerOptions,
       pageRangeCache,
       getPageRangePdf,
@@ -8277,6 +8291,8 @@ function createExtractor(config) {
         generateObject,
         convertPdfToImages,
         maxTokens: budget.maxTokens,
+        taskKind: "extraction_focused",
+        budgetDiagnostics: budget,
         providerOptions: activeProviderOptions,
         pageRangeCache,
         getPageRangePdf,
@@ -8425,6 +8441,8 @@ function createExtractor(config) {
           prompt: buildClassifyPrompt(),
           schema: ClassifyResultSchema,
           maxTokens: budget.maxTokens,
+          taskKind: "extraction_classify",
+          budgetDiagnostics: budget,
           providerOptions: await getFullPdfProviderOptions()
         },
         {
@@ -8473,6 +8491,8 @@ function createExtractor(config) {
           prompt: buildFormInventoryPrompt(templateHints),
           schema: FormInventorySchema,
           maxTokens: budget.maxTokens,
+          taskKind: "extraction_form_inventory",
+          budgetDiagnostics: budget,
           providerOptions: await getFullPdfProviderOptions()
         },
         {
@@ -8525,6 +8545,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 }
               },
               {
@@ -8641,6 +8663,8 @@ function createExtractor(config) {
             generateObject,
             convertPdfToImages,
             maxTokens: budget.maxTokens,
+            taskKind: "extraction_focused",
+            budgetDiagnostics: budget,
             providerOptions: activeProviderOptions,
             pageRangeCache: completedPageRangePdfCache,
             getPageRangePdf,
@@ -8731,10 +8755,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}`)
             }
@@ -8835,6 +8868,8 @@ function createExtractor(config) {
             prompt: buildSummaryPrompt(document),
             schema: SummaryResultSchema,
             maxTokens: budget.maxTokens,
+            taskKind: "extraction_summary",
+            budgetDiagnostics: budget,
             providerOptions: activeProviderOptions
           },
           {
@@ -8862,6 +8897,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
@@ -9264,6 +9301,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
@@ -9366,6 +9404,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
@@ -9419,6 +9458,7 @@ async function autoFillFromContext(fields, orgContext, generateObject, providerO
       prompt,
       schema: AutoFillResultSchema,
       maxTokens,
+      taskKind: "application_auto_fill",
       providerOptions
     })
   );
@@ -9489,6 +9529,7 @@ async function batchQuestions(unfilledFields, generateObject, providerOptions, m
       prompt,
       schema: QuestionBatchResultSchema,
       maxTokens,
+      taskKind: "application_batch",
       providerOptions
     })
   );
@@ -9540,6 +9581,7 @@ async function classifyReplyIntent(fields, replyText, generateObject, providerOp
       prompt,
       schema: ReplyIntentSchema,
       maxTokens,
+      taskKind: "application_classify",
       providerOptions
     })
   );
@@ -9599,6 +9641,7 @@ async function parseAnswers(fields, replyText, generateObject, providerOptions,
       prompt,
       schema: AnswerParsingResultSchema,
       maxTokens,
+      taskKind: "application_parse_answers",
       providerOptions
     })
   );
@@ -9728,6 +9771,7 @@ async function fillFromLookup(requests, targetFields, availableData, generateObj
       prompt,
       schema: LookupFillResultSchema,
       maxTokens,
+      taskKind: "application_lookup",
       providerOptions
     })
   );
@@ -9810,6 +9854,7 @@ async function generateBatchEmail(batchFields, batchIndex, totalBatches, opts, g
     () => generateText({
       prompt,
       maxTokens,
+      taskKind: "application_email",
       providerOptions
     })
   );
@@ -10332,11 +10377,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);
@@ -10461,6 +10509,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.
 
@@ -10468,7 +10517,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);
@@ -10942,6 +10993,8 @@ ${e.text}`;
       prompt,
       schema: SubAnswerSchema,
       maxTokens: budget.maxTokens,
+      taskKind: "query_reason",
+      budgetDiagnostics: budget,
       providerOptions
     })
   );
@@ -11165,6 +11218,8 @@ async function verify(originalQuestion, subAnswers, allEvidence, config) {
       prompt,
       schema: VerifyResultSchema,
       maxTokens: budget.maxTokens,
+      taskKind: "query_verify",
+      budgetDiagnostics: budget,
       providerOptions
     })
   );
@@ -11307,6 +11362,8 @@ async function interpretAttachments(params) {
         prompt,
         schema: AttachmentInterpretationSchema,
         maxTokens: budget.maxTokens,
+        taskKind: "query_attachment",
+        budgetDiagnostics: budget,
         providerOptions: buildAttachmentProviderOptions(attachment, providerOptions)
       },
       {
@@ -11644,6 +11701,8 @@ function createQueryAgent(config) {
         prompt,
         schema: QueryClassifyResultSchema,
         maxTokens: budget.maxTokens,
+        taskKind: "query_classify",
+        budgetDiagnostics: budget,
         providerOptions
       },
       {
@@ -11695,6 +11754,8 @@ function createQueryAgent(config) {
         prompt,
         schema: QueryResultSchema,
         maxTokens: budget.maxTokens,
+        taskKind: "query_respond",
+        budgetDiagnostics: budget,
         providerOptions
       },
       {
@@ -11790,6 +11851,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 }
@@ -11851,6 +11914,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 }