@claritylabs/cl-sdk 0.12.0 → 0.13.1

package/dist/index.js

@@ -40,6 +40,7 @@ __export(index_exports, {
   AuditTypeSchema: () => AuditTypeSchema,
   AutoFillMatchSchema: () => AutoFillMatchSchema,
   AutoFillResultSchema: () => AutoFillResultSchema,
+  AuxiliaryFactSchema: () => AuxiliaryFactSchema,
   BOAT_TYPES: () => BOAT_TYPES,
   BindingAuthoritySchema: () => BindingAuthoritySchema,
   BoatTypeSchema: () => BoatTypeSchema,
@@ -1471,6 +1472,12 @@ var PremiumLineSchema = import_zod16.z.object({
   line: import_zod16.z.string(),
   amount: import_zod16.z.string()
 });
+var AuxiliaryFactSchema = import_zod16.z.object({
+  key: import_zod16.z.string(),
+  value: import_zod16.z.string(),
+  subject: import_zod16.z.string().optional(),
+  context: import_zod16.z.string().optional()
+});
 var BaseDocumentFields = {
   id: import_zod16.z.string(),
   carrier: import_zod16.z.string(),
@@ -1536,7 +1543,8 @@ var BaseDocumentFields = {
   individualClaims: import_zod16.z.array(ClaimRecordSchema).optional(),
   experienceMod: ExperienceModSchema.optional(),
   cancellationNoticeDays: import_zod16.z.number().optional(),
-  nonrenewalNoticeDays: import_zod16.z.number().optional()
+  nonrenewalNoticeDays: import_zod16.z.number().optional(),
+  supplementaryFacts: import_zod16.z.array(AuxiliaryFactSchema).optional()
 };
 var PolicyDocumentSchema = import_zod16.z.object({
   ...BaseDocumentFields,
@@ -2199,6 +2207,7 @@ function assembleDocument(documentId, documentType, memory) {
     ...sanitizeNulls(coverages ?? {}),
     ...sanitizeNulls(premium ?? {}),
     ...sanitizeNulls(supplementary ?? {}),
+    supplementaryFacts: supplementary?.auxiliaryFacts,
     endorsements: endorsements?.endorsements,
     exclusions: exclusions?.exclusions,
     conditions: conditions?.conditions,
@@ -2551,6 +2560,43 @@ Total Cost: ${doc.totalCost}` : ""}`,
       metadata: stringMetadata({ premium: doc.premium, documentType: doc.type })
     });
   }
+  const supplementaryLines = [
+    ...doc.claimsContacts?.map((contact) => `Claims Contact: ${[
+      contact.name,
+      contact.phone,
+      contact.email,
+      contact.hours
+    ].filter(Boolean).join(" | ")}`) ?? [],
+    ...doc.regulatoryContacts?.map((contact) => `Regulatory Contact: ${[
+      contact.name,
+      contact.phone,
+      contact.email
+    ].filter(Boolean).join(" | ")}`) ?? [],
+    ...doc.thirdPartyAdministrators?.map((contact) => `TPA: ${[
+      contact.name,
+      contact.phone,
+      contact.email
+    ].filter(Boolean).join(" | ")}`) ?? [],
+    ...doc.supplementaryFacts?.map((fact) => [
+      fact.subject ? `Subject: ${fact.subject}` : null,
+      `${fact.key}: ${fact.value}`,
+      fact.context ? `Context: ${fact.context}` : null
+    ].filter(Boolean).join(" | ")) ?? [],
+    doc.cancellationNoticeDays != null ? `Cancellation Notice Days: ${doc.cancellationNoticeDays}` : null,
+    doc.nonrenewalNoticeDays != null ? `Nonrenewal Notice Days: ${doc.nonrenewalNoticeDays}` : null
+  ].filter((line) => Boolean(line));
+  if (supplementaryLines.length > 0) {
+    chunks.push({
+      id: `${docId}:supplementary:0`,
+      documentId: docId,
+      type: "supplementary",
+      text: supplementaryLines.join("\n"),
+      metadata: stringMetadata({
+        documentType: doc.type,
+        supplementaryFactCount: doc.supplementaryFacts?.length
+      })
+    });
+  }
   return chunks;
 }
 
@@ -2634,6 +2680,32 @@ function mergeArrayPayload(existing, incoming, arrayKey, keyFn) {
   merged[arrayKey] = mergeUniqueObjects(existingItems, incomingItems, keyFn);
   return merged;
 }
+function mergeSupplementary(existing, incoming) {
+  const merged = mergeShallowPreferPresent(existing, incoming);
+  const mergeContactArray = (arrayKey) => {
+    const existingItems = Array.isArray(existing[arrayKey]) ? existing[arrayKey] : [];
+    const incomingItems = Array.isArray(incoming[arrayKey]) ? incoming[arrayKey] : [];
+    merged[arrayKey] = mergeUniqueObjects(existingItems, incomingItems, (item) => [
+      String(item.name ?? "").toLowerCase(),
+      String(item.phone ?? "").toLowerCase(),
+      String(item.email ?? "").toLowerCase(),
+      String(item.address ?? "").toLowerCase(),
+      String(item.type ?? "").toLowerCase()
+    ].join("|"));
+  };
+  mergeContactArray("regulatoryContacts");
+  mergeContactArray("claimsContacts");
+  mergeContactArray("thirdPartyAdministrators");
+  const existingFacts = Array.isArray(existing.auxiliaryFacts) ? existing.auxiliaryFacts : [];
+  const incomingFacts = Array.isArray(incoming.auxiliaryFacts) ? incoming.auxiliaryFacts : [];
+  merged.auxiliaryFacts = mergeUniqueObjects(existingFacts, incomingFacts, (item) => [
+    String(item.key ?? "").toLowerCase(),
+    String(item.value ?? "").toLowerCase(),
+    String(item.subject ?? "").toLowerCase(),
+    String(item.context ?? "").toLowerCase()
+  ].join("|"));
+  return merged;
+}
 function mergeExtractorResult(extractorName, existing, incoming) {
   if (!existing) return incoming;
   if (!incoming) return existing;
@@ -2644,9 +2716,10 @@ function mergeExtractorResult(extractorName, existing, incoming) {
     case "carrier_info":
     case "named_insured":
     case "loss_history":
-    case "supplementary":
     case "premium_breakdown":
       return mergeShallowPreferPresent(current, next);
+    case "supplementary":
+      return mergeSupplementary(current, next);
     case "coverage_limits":
       return mergeCoverageLimits(current, next);
     case "declarations":
@@ -4243,16 +4316,29 @@ var ContactSchema2 = import_zod33.z.object({
   address: import_zod33.z.string().optional().describe("Mailing address"),
   type: import_zod33.z.string().optional().describe("Contact type, e.g. 'State Department of Insurance'")
 });
+var AuxiliaryFactSchema2 = import_zod33.z.object({
+  key: import_zod33.z.string().describe("Normalized machine-readable fact key, e.g. 'policyholder_age' or 'insured_name'"),
+  value: import_zod33.z.string().describe("Concrete extracted fact value"),
+  subject: import_zod33.z.string().optional().describe("Person, entity, vehicle, property, or schedule item this fact belongs to"),
+  context: import_zod33.z.string().optional().describe("Short disambiguating context, such as 'Driver Schedule' or 'Named Insured'")
+});
 var SupplementarySchema = import_zod33.z.object({
   regulatoryContacts: import_zod33.z.array(ContactSchema2).optional().describe("Regulatory body contacts (state department of insurance, ombudsman)"),
   claimsContacts: import_zod33.z.array(ContactSchema2).optional().describe("Claims reporting contacts and instructions"),
   thirdPartyAdministrators: import_zod33.z.array(ContactSchema2).optional().describe("Third-party administrators for claims handling"),
   cancellationNoticeDays: import_zod33.z.number().optional().describe("Required notice period for cancellation in days"),
-  nonrenewalNoticeDays: import_zod33.z.number().optional().describe("Required notice period for nonrenewal in days")
+  nonrenewalNoticeDays: import_zod33.z.number().optional().describe("Required notice period for nonrenewal in days"),
+  auxiliaryFacts: import_zod33.z.array(AuxiliaryFactSchema2).optional().describe("Additional retrieval-only facts that do not fit the strict primary schema")
 });
-function buildSupplementaryPrompt() {
-  return `You are an expert insurance document analyst. Extract supplementary and regulatory information from this document.
+function buildSupplementaryPrompt(alreadyExtractedSummary) {
+  const exclusionBlock = alreadyExtractedSummary ? `
 
+IMPORTANT \u2014 The following facts have ALREADY been captured by prior extraction passes. Do NOT re-extract any of these. Your job is to find ADDITIONAL information that is missing from this list:
+
+${alreadyExtractedSummary}
+` : "";
+  return `You are an expert insurance document analyst. Extract supplementary, retrieval-only information from this document that is NOT already captured in the structured extraction results.
+${exclusionBlock}
 Focus on:
 - Regulatory contacts: state department of insurance, regulatory bodies, ombudsman offices \u2014 with phone, email, address
 - Claims contacts: how to report claims, claims department contact info, hours of operation
@@ -4261,9 +4347,21 @@ Focus on:
 - Nonrenewal notice period in days
 - Complaint filing procedures and contacts
 - Governing law or jurisdiction provisions
+- Additional policy-specific facts that are useful for memory and retrieval even if they do not belong in the strict primary schema
 
 Look for regulatory notices, complaint contact sections, claims reporting instructions, and cancellation/nonrenewal provisions throughout the document.
 
+For auxiliaryFacts:
+- ONLY capture facts that are NOT already present in the structured extraction results above.
+- Do not duplicate information that has already been extracted \u2014 no policy numbers, insured names, addresses, coverage limits, deductibles, or any other field that appears in the already-extracted data.
+- Capture concrete, policy-specific facts as structured key/value pairs.
+- Prioritize facts that agents may need later but that are often omitted from strict schemas: policyholder names, insured person names, driver names, ages, dates of birth, marital status, garaging information, lienholders, household members, vehicle assignments, schedule row details, and other discrete identifiers \u2014 but ONLY if they are not already in the extracted data.
+- Use short normalized keys like "policyholder_name", "policyholder_age", "insured_name", "driver_age", "driver_date_of_birth", "garaging_zip", "vehicle_principal_driver".
+- Use subject when the fact belongs to a specific person, vehicle, property, or scheduled item.
+- Do not invent facts.
+- Do not include vague boilerplate or generic form language.
+- Do not repeat large narrative excerpts; keep facts atomic.
+
 Return JSON only.`;
 }
 
@@ -4651,6 +4749,38 @@ function createExtractor(config) {
       sectionCount: Array.isArray(sectionResult?.sections) ? sectionResult.sections.length : 0
     }, null, 2);
   }
+  function buildAlreadyExtractedSummary(memory) {
+    const lines = [];
+    const declarationResult = memory.get("declarations");
+    if (Array.isArray(declarationResult?.fields)) {
+      for (const field of declarationResult.fields) {
+        if (field.key && field.value) {
+          const subject = field.subject ? ` [${field.subject}]` : "";
+          lines.push(`- ${field.key}${subject}: ${field.value}`);
+        }
+      }
+    }
+    const coverageResult = memory.get("coverage_limits");
+    if (Array.isArray(coverageResult?.coverages)) {
+      for (const cov of coverageResult.coverages) {
+        const parts = [cov.name, cov.limit && `limit=${cov.limit}`, cov.deductible && `deductible=${cov.deductible}`].filter(Boolean);
+        if (parts.length > 0) lines.push(`- coverage: ${parts.join(", ")}`);
+      }
+    }
+    const namedInsured = memory.get("named_insured");
+    if (namedInsured) {
+      for (const [key, value] of Object.entries(namedInsured)) {
+        if (value && typeof value === "string") lines.push(`- ${key}: ${value}`);
+      }
+    }
+    const carrierInfo = memory.get("carrier_info");
+    if (carrierInfo) {
+      for (const [key, value] of Object.entries(carrierInfo)) {
+        if (value && typeof value === "string") lines.push(`- ${key}: ${value}`);
+      }
+    }
+    return lines.length > 0 ? lines.join("\n") : "";
+  }
   function formatPageMapSummary(pageAssignments) {
     const extractorPages = /* @__PURE__ */ new Map();
     for (const assignment of pageAssignments) {
@@ -4990,6 +5120,28 @@ function createExtractor(config) {
           mergeMemoryResult(result.name, result.data, memory);
         }
       }
+      {
+        onProgress?.("Extracting supplementary retrieval facts...");
+        try {
+          const alreadyExtractedSummary = buildAlreadyExtractedSummary(memory);
+          const supplementaryResult = await runExtractor({
+            name: "supplementary",
+            prompt: buildSupplementaryPrompt(alreadyExtractedSummary),
+            schema: SupplementarySchema,
+            pdfBase64,
+            startPage: 1,
+            endPage: pageCount,
+            generateObject,
+            convertPdfToImages,
+            maxTokens: 4096,
+            providerOptions
+          });
+          trackUsage(supplementaryResult.usage);
+          mergeMemoryResult(supplementaryResult.name, supplementaryResult.data, memory);
+        } catch (error) {
+          await log?.(`Supplementary extractor failed: ${error}`);
+        }
+      }
       await pipelineCtx.save("extract", {
         id,
         pageCount,
@@ -7706,6 +7858,7 @@ var AGENT_TOOLS = [
   AuditTypeSchema,
   AutoFillMatchSchema,
   AutoFillResultSchema,
+  AuxiliaryFactSchema,
   BOAT_TYPES,
   BindingAuthoritySchema,
   BoatTypeSchema,