@claritylabs/cl-sdk 0.7.4 → 0.8.0

package/dist/index.d.mts

@@ -12,7 +12,16 @@ type GenerateText = (params: {
     text: string;
     usage?: TokenUsage;
 }>;
-/** Callback to generate a typed object from a prompt + Zod schema. Provider-agnostic. */
+/**
+ * Callback to generate a typed object from a prompt + Zod schema. Provider-agnostic.
+ *
+ * The extraction pipeline passes document content via `providerOptions`:
+ * - `providerOptions.pdfBase64` — base64-encoded PDF to include as document context
+ * - `providerOptions.images` — `Array<{ imageBase64: string; mimeType: string }>` page images
+ *
+ * Your callback should check for these fields and include them as multi-part
+ * message content (e.g. file/image parts) when calling your AI provider.
+ */
 type GenerateObject<T = unknown> = (params: {
     prompt: string;
     system?: string;

package/dist/index.d.ts

@@ -12,7 +12,16 @@ type GenerateText = (params: {
     text: string;
     usage?: TokenUsage;
 }>;
-/** Callback to generate a typed object from a prompt + Zod schema. Provider-agnostic. */
+/**
+ * Callback to generate a typed object from a prompt + Zod schema. Provider-agnostic.
+ *
+ * The extraction pipeline passes document content via `providerOptions`:
+ * - `providerOptions.pdfBase64` — base64-encoded PDF to include as document context
+ * - `providerOptions.images` — `Array<{ imageBase64: string; mimeType: string }>` page images
+ *
+ * Your callback should check for these fields and include them as multi-part
+ * message content (e.g. file/image parts) when calling your AI provider.
+ */
 type GenerateObject<T = unknown> = (params: {
     prompt: string;
     system?: string;

package/dist/index.js

@@ -1758,19 +1758,28 @@ async function runExtractor(params) {
     maxTokens = 4096,
     providerOptions
   } = params;
-  const pagesPdf = await extractPageRange(pdfBase64, startPage, endPage);
-  const fullPrompt = convertPdfToImages ? `${prompt}
-
-[Document pages ${startPage}-${endPage} are provided as images above.]` : `${prompt}
+  const extractorProviderOptions = { ...providerOptions };
+  let fullPrompt;
+  if (convertPdfToImages) {
+    const images = await convertPdfToImages(pdfBase64, startPage, endPage);
+    extractorProviderOptions.images = images;
+    fullPrompt = `${prompt}
+
+[Document pages ${startPage}-${endPage} are provided as images.]`;
+  } else {
+    const pagesPdf = await extractPageRange(pdfBase64, startPage, endPage);
+    extractorProviderOptions.pdfBase64 = pagesPdf;
+    fullPrompt = `${prompt}
 
-[Document pages ${startPage}-${endPage} are provided as a PDF file above.]`;
+[Document pages ${startPage}-${endPage} are provided as a PDF file.]`;
+  }
   const strictSchema = toStrictSchema(schema);
   const result = await withRetry(
     () => generateObject({
       prompt: fullPrompt,
       schema: strictSchema,
       maxTokens,
-      providerOptions
+      providerOptions: extractorProviderOptions
     })
   );
   return {
@@ -2849,29 +2858,73 @@ function getTemplate(policyType) {
 // src/prompts/coordinator/classify.ts
 var import_zod18 = require("zod");
 var ClassifyResultSchema = import_zod18.z.object({
-  documentType: import_zod18.z.enum(["policy", "quote"]),
-  policyTypes: import_zod18.z.array(PolicyTypeSchema),
-  confidence: import_zod18.z.number()
+  documentType: import_zod18.z.enum(["policy", "quote"]).describe("Whether this is a bound policy or a proposed quote"),
+  policyTypes: import_zod18.z.array(PolicyTypeSchema).min(1).describe("Lines of business covered \u2014 at least one required"),
+  confidence: import_zod18.z.number().describe("Confidence score from 0.0 to 1.0")
 });
 function buildClassifyPrompt() {
-  return `You are classifying an insurance document. Examine the first few pages and determine:
+  return `You are classifying an insurance document. Examine the document and determine:
 
 1. Whether this is a POLICY (bound coverage) or QUOTE (proposed coverage)
-2. What lines of business are covered
-
-Policies typically have: policy numbers, effective/expiration dates, declarations pages, premium charges.
-Quotes typically have: quote numbers, proposed dates, subjectivities, "indication" or "proposal" language.
-
-Return JSON matching this structure:
+2. What lines of business are covered (at least one \u2014 never return an empty list)
+
+POLICY indicators: policy numbers, effective/expiration dates, declarations pages, premium charges, "this policy" language.
+QUOTE indicators: quote numbers, proposed dates, subjectivities, "indication" or "proposal" language, "quoted premium".
+
+COMMERCIAL LINES \u2014 match these values:
+- "general_liability" \u2014 CGL, commercial general liability, GL
+- "commercial_property" \u2014 commercial property, building/contents coverage
+- "commercial_auto" \u2014 commercial auto, business auto, CA
+- "non_owned_auto" \u2014 hired & non-owned auto
+- "workers_comp" \u2014 workers compensation, WC
+- "umbrella" \u2014 commercial umbrella
+- "excess_liability" \u2014 excess liability, follow-form excess
+- "professional_liability" \u2014 E&O, errors & omissions, professional liability, malpractice
+- "cyber" \u2014 cyber liability, data breach, network security
+- "epli" \u2014 employment practices liability
+- "directors_officers" \u2014 D&O, directors and officers
+- "fiduciary_liability" \u2014 fiduciary liability
+- "crime_fidelity" \u2014 crime, fidelity, employee dishonesty
+- "inland_marine" \u2014 inland marine, equipment floater, contractors equipment
+- "builders_risk" \u2014 builders risk, course of construction
+- "environmental" \u2014 environmental, pollution liability
+- "ocean_marine" \u2014 ocean marine, cargo, hull
+- "surety" \u2014 surety bond
+- "product_liability" \u2014 product liability, products-completed operations
+- "bop" \u2014 business owners policy, BOP
+- "management_liability_package" \u2014 management liability package
+- "property" \u2014 standalone property
+
+PERSONAL LINES \u2014 match these values:
+- "homeowners_ho3" \u2014 HO-3, special form homeowners
+- "homeowners_ho5" \u2014 HO-5, comprehensive form homeowners
+- "renters_ho4" \u2014 HO-4, renters insurance
+- "condo_ho6" \u2014 HO-6, condo unit-owners
+- "dwelling_fire" \u2014 DP-1, DP-3, dwelling fire
+- "mobile_home" \u2014 mobile home, manufactured home
+- "personal_auto" \u2014 personal auto, PAP
+- "personal_umbrella" \u2014 personal umbrella
+- "flood_nfip" \u2014 NFIP flood
+- "flood_private" \u2014 private flood
+- "earthquake" \u2014 earthquake
+- "personal_inland_marine" \u2014 personal articles, scheduled personal property
+- "watercraft" \u2014 watercraft, boat
+- "recreational_vehicle" \u2014 RV, recreational vehicle, ATV
+- "farm_ranch" \u2014 farm, ranch
+- "pet" \u2014 pet insurance
+- "travel" \u2014 travel insurance
+- "identity_theft" \u2014 identity theft
+- "title" \u2014 title insurance
+- "other" \u2014 only if NONE of the above match
+
+IMPORTANT: You must identify at least one specific policy type. Only use "other" as a last resort when the document truly does not match any known type.
+
+Return JSON only:
 {
   "documentType": "policy" | "quote",
-  "policyTypes": ["general_liability", "commercial_property", ...],
+  "policyTypes": ["general_liability", ...],
   "confidence": 0.0-1.0
-}
-
-Use these policy type values: general_liability, commercial_property, commercial_auto, non_owned_auto, workers_comp, umbrella, excess_liability, professional_liability, cyber, epli, directors_officers, fiduciary_liability, crime_fidelity, inland_marine, builders_risk, environmental, ocean_marine, surety, product_liability, bop, management_liability_package, property, homeowners_ho3, homeowners_ho5, renters_ho4, condo_ho6, dwelling_fire, mobile_home, personal_auto, personal_umbrella, flood_nfip, flood_private, earthquake, personal_inland_marine, watercraft, recreational_vehicle, farm_ranch, pet, travel, identity_theft, title, other.
-
-Respond with JSON only.`;
+}`;
 }
 
 // src/prompts/coordinator/plan.ts
@@ -3546,16 +3599,20 @@ function createExtractor(config) {
           prompt: buildClassifyPrompt(),
           schema: ClassifyResultSchema,
           maxTokens: 512,
-          providerOptions
+          providerOptions: { ...providerOptions, pdfBase64 }
         },
         {
           fallback: { documentType: "policy", policyTypes: ["other"], confidence: 0 },
+          maxRetries: 3,
           log,
-          onError: (err, attempt) => log?.(`Classify attempt ${attempt + 1} failed: ${err}`)
+          onError: (err, attempt) => log?.(`Classify attempt ${attempt + 1} failed: ${err instanceof Error ? err.message : String(err)}`)
         }
       );
       trackUsage(classifyResponse.usage);
       classifyResult = classifyResponse.object;
+      if (classifyResult.confidence === 0) {
+        await log?.(`WARNING: classify returned fallback (policyTypes: ["other"]). This usually means the generateObject callback failed \u2014 check that the document content is accessible to the model.`);
+      }
       memory.set("classify", classifyResult);
       await pipelineCtx.save("classify", {
         id,
@@ -3586,7 +3643,7 @@ function createExtractor(config) {
           prompt: buildPlanPrompt(templateHints),
           schema: ExtractionPlanSchema,
           maxTokens: 2048,
-          providerOptions
+          providerOptions: { ...providerOptions, pdfBase64 }
         },
         {
           fallback: {