@claritylabs/cl-sdk 0.7.3 → 0.7.5

package/dist/index.mjs

@@ -92,29 +92,40 @@ function toStrictSchema(schema) {
       const fieldType = fieldDef?.type ?? field.type;
       if (fieldType === "optional") {
         const innerType = fieldDef?.innerType;
+        const description = field.description ?? fieldDef?.description ?? field._zod?.def?.description;
         if (innerType) {
           const transformed = toStrictSchema(innerType);
-          newShape[key] = z.nullable(transformed);
+          let nullable = z.nullable(transformed);
+          if (description) nullable = nullable.describe(description);
+          newShape[key] = nullable;
         } else {
-          newShape[key] = z.nullable(field);
+          let nullable = z.nullable(field);
+          if (description) nullable = nullable.describe(description);
+          newShape[key] = nullable;
         }
       } else {
         newShape[key] = toStrictSchema(field);
       }
     }
-    return z.object(newShape);
+    const objDesc = schema.description ?? def?.description ?? schema._zod?.def?.description;
+    const result = z.object(newShape);
+    return objDesc ? result.describe(objDesc) : result;
   }
   if (typeName === "array") {
     const element = def?.element ?? schema.element;
     if (element) {
-      return z.array(toStrictSchema(element));
+      const arrDesc = schema.description ?? def?.description ?? schema._zod?.def?.description;
+      const result = z.array(toStrictSchema(element));
+      return arrDesc ? result.describe(arrDesc) : result;
     }
     return schema;
   }
   if (typeName === "nullable") {
     const innerType = def?.innerType;
     if (innerType) {
-      return z.nullable(toStrictSchema(innerType));
+      const nullDesc = schema.description ?? def?.description ?? schema._zod?.def?.description;
+      const result = z.nullable(toStrictSchema(innerType));
+      return nullDesc ? result.describe(nullDesc) : result;
     }
     return schema;
   }
@@ -2605,29 +2616,73 @@ function getTemplate(policyType) {
 // src/prompts/coordinator/classify.ts
 import { z as z18 } from "zod";
 var ClassifyResultSchema = z18.object({
-  documentType: z18.enum(["policy", "quote"]),
-  policyTypes: z18.array(PolicyTypeSchema),
-  confidence: z18.number()
+  documentType: z18.enum(["policy", "quote"]).describe("Whether this is a bound policy or a proposed quote"),
+  policyTypes: z18.array(PolicyTypeSchema).min(1).describe("Lines of business covered \u2014 at least one required"),
+  confidence: z18.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
@@ -2846,27 +2901,71 @@ import { z as z24 } from "zod";
 var EndorsementsSchema = z24.object({
   endorsements: z24.array(
     z24.object({
-      formNumber: z24.string().optional().describe("Form number, e.g. 'CG 21 47'"),
-      title: z24.string().optional().describe("Endorsement title"),
-      type: z24.enum(["broadening", "restrictive", "informational"]).optional().describe("Effect type: broadening adds coverage, restrictive limits it"),
-      content: z24.string().optional().describe("Full verbatim text of the endorsement"),
+      formNumber: z24.string().describe("Form number, e.g. 'CG 21 47'"),
+      editionDate: z24.string().optional().describe("Edition date, e.g. '12 07'"),
+      title: z24.string().describe("Endorsement title"),
+      endorsementType: z24.enum([
+        "additional_insured",
+        "waiver_of_subrogation",
+        "primary_noncontributory",
+        "blanket_additional_insured",
+        "loss_payee",
+        "mortgage_holder",
+        "broadening",
+        "restriction",
+        "exclusion",
+        "amendatory",
+        "notice_of_cancellation",
+        "designated_premises",
+        "classification_change",
+        "schedule_update",
+        "deductible_change",
+        "limit_change",
+        "territorial_extension",
+        "other"
+      ]).describe("Endorsement type classification"),
       effectiveDate: z24.string().optional().describe("Endorsement effective date"),
-      premium: z24.string().optional().describe("Additional premium or credit"),
-      parties: z24.array(z24.string()).optional().describe("Named parties (additional insureds, loss payees, etc.)")
+      affectedCoverageParts: z24.array(z24.string()).optional().describe("Coverage parts affected by this endorsement"),
+      namedParties: z24.array(
+        z24.object({
+          name: z24.string().describe("Party name"),
+          role: z24.enum([
+            "additional_insured",
+            "loss_payee",
+            "mortgage_holder",
+            "certificate_holder",
+            "waiver_beneficiary",
+            "designated_person",
+            "other"
+          ]).describe("Party role"),
+          relationship: z24.string().optional().describe("Relationship to insured"),
+          scope: z24.string().optional().describe("Scope of coverage for this party")
+        })
+      ).optional().describe("Named parties (additional insureds, loss payees, etc.)"),
+      keyTerms: z24.array(z24.string()).optional().describe("Key terms or notable provisions in the endorsement"),
+      premiumImpact: z24.string().optional().describe("Additional premium or credit"),
+      content: z24.string().describe("Full verbatim text of the endorsement"),
+      pageStart: z24.number().describe("Starting page number of this endorsement"),
+      pageEnd: z24.number().optional().describe("Ending page number of this endorsement")
     })
   ).describe("All endorsements found in the document")
 });
 function buildEndorsementsPrompt() {
   return `You are an expert insurance document analyst. Extract ALL endorsements from this document. Preserve original language verbatim.
 
-Focus on:
-- Every endorsement listed in the forms schedule or endorsement schedule
-- Standalone endorsements modifying the base policy
-- Form number and edition date (e.g. "CG 21 47 12 07")
-- Endorsement title and full verbatim content
-- Effect type: "broadening" if it adds or expands coverage, "restrictive" if it limits or excludes coverage, "informational" if it changes administrative terms only
-- Additional premium or credit shown on the endorsement
-- Named parties: additional insureds, loss payees, certificate holders, mortgagees
+For EACH endorsement, extract:
+- formNumber: the form identifier (e.g. "CG 21 47") \u2014 REQUIRED
+- editionDate: the edition date if present (e.g. "12 07")
+- title: endorsement title \u2014 REQUIRED
+- endorsementType: classify as one of: additional_insured, waiver_of_subrogation, primary_noncontributory, blanket_additional_insured, loss_payee, mortgage_holder, broadening, restriction, exclusion, amendatory, notice_of_cancellation, designated_premises, classification_change, schedule_update, deductible_change, limit_change, territorial_extension, other
+- effectiveDate: endorsement effective date if shown
+- affectedCoverageParts: which coverage parts are modified
+- namedParties: for each party, extract name, role (additional_insured, loss_payee, mortgage_holder, certificate_holder, waiver_beneficiary, designated_person, other), relationship, and scope
+- keyTerms: notable provisions or key terms
+- premiumImpact: additional premium or credit if shown
+- content: full verbatim text \u2014 REQUIRED
+- pageStart: page number where endorsement begins \u2014 REQUIRED
+- pageEnd: page number where endorsement ends
 
 PERSONAL LINES ENDORSEMENT RECOGNITION:
 - HO 04 XX series: homeowners endorsements
@@ -2882,23 +2981,39 @@ import { z as z25 } from "zod";
 var ExclusionsSchema = z25.object({
   exclusions: z25.array(
     z25.object({
-      title: z25.string().describe("Exclusion title or short description"),
-      content: z25.string().optional().describe("Full verbatim exclusion text"),
+      name: z25.string().describe("Exclusion title or short description"),
       formNumber: z25.string().optional().describe("Form number if part of a named endorsement"),
-      appliesTo: z25.string().optional().describe("Coverage type this exclusion applies to")
+      excludedPerils: z25.array(z25.string()).optional().describe("Specific perils excluded"),
+      isAbsolute: z25.boolean().optional().describe("Whether the exclusion is absolute (no exceptions)"),
+      exceptions: z25.array(z25.string()).optional().describe("Exceptions to the exclusion, if any"),
+      buybackAvailable: z25.boolean().optional().describe("Whether coverage can be bought back via endorsement"),
+      buybackEndorsement: z25.string().optional().describe("Form number of the buyback endorsement if available"),
+      appliesTo: z25.array(z25.string()).optional().describe("Coverage types this exclusion applies to"),
+      content: z25.string().describe("Full verbatim exclusion text"),
+      pageNumber: z25.number().optional().describe("Page number where exclusion appears")
     })
   ).describe("All exclusions found in the document")
 });
 function buildExclusionsPrompt() {
   return `You are an expert insurance document analyst. Extract ALL exclusions from this document. Preserve original language verbatim.
 
+For EACH exclusion, extract:
+- name: exclusion title or short description \u2014 REQUIRED
+- formNumber: form number if the exclusion is part of a named endorsement
+- excludedPerils: specific perils being excluded
+- isAbsolute: true if the exclusion has no exceptions, false if exceptions exist
+- exceptions: any exceptions to the exclusion (things still covered despite the exclusion)
+- buybackAvailable: whether coverage can be purchased back via endorsement
+- buybackEndorsement: the form number of the buyback endorsement if known
+- appliesTo: which coverage types or lines this exclusion applies to (as an array)
+- content: full verbatim exclusion text \u2014 REQUIRED
+- pageNumber: page number where the exclusion appears
+
 Focus on:
 - Named exclusions from exclusion schedules
 - Exclusions embedded within endorsements
 - Exclusions within insuring agreements or conditions if clearly labeled
 - Full verbatim exclusion text \u2014 do not summarize
-- Form number if the exclusion is part of a named endorsement
-- Which coverage line the exclusion applies to, if specific
 
 Common personal lines exclusion patterns: animal liability, business pursuits, home daycare, watercraft, aircraft.
 
@@ -2910,43 +3025,62 @@ import { z as z26 } from "zod";
 var ConditionsSchema = z26.object({
   conditions: z26.array(
     z26.object({
-      type: z26.enum([
+      name: z26.string().describe("Condition title"),
+      conditionType: z26.enum([
         "duties_after_loss",
-        "cooperation",
+        "notice_requirements",
+        "other_insurance",
         "cancellation",
         "nonrenewal",
-        "subrogation",
-        "other_insurance",
         "transfer_of_rights",
-        "examination_under_oath",
-        "arbitration",
-        "suit_against_us",
         "liberalization",
+        "arbitration",
+        "concealment_fraud",
+        "examination_under_oath",
+        "legal_action",
+        "loss_payment",
+        "appraisal",
+        "mortgage_holders",
+        "policy_territory",
+        "separation_of_insureds",
         "other"
-      ]).optional().describe("Condition category"),
-      title: z26.string().describe("Condition title"),
-      content: z26.string().optional().describe("Full verbatim condition text"),
-      noticeDays: z26.number().optional().describe("Notice period in days if specified (e.g. cancellation notice)")
+      ]).describe("Condition category"),
+      content: z26.string().describe("Full verbatim condition text"),
+      keyValues: z26.array(
+        z26.object({
+          key: z26.string().describe("Key name (e.g. 'noticePeriod', 'suitDeadline')"),
+          value: z26.string().describe("Value (e.g. '30 days', '2 years')")
+        })
+      ).optional().describe("Key values extracted from the condition (notice periods, deadlines, etc.)"),
+      pageNumber: z26.number().optional().describe("Page number where condition appears")
     })
   ).describe("All policy conditions found in the document")
 });
 function buildConditionsPrompt() {
   return `You are an expert insurance document analyst. Extract ALL policy conditions from this document. Preserve original language verbatim.
 
+For EACH condition, extract:
+- name: condition title \u2014 REQUIRED
+- conditionType: classify as one of: duties_after_loss, notice_requirements, other_insurance, cancellation, nonrenewal, transfer_of_rights, liberalization, arbitration, concealment_fraud, examination_under_oath, legal_action, loss_payment, appraisal, mortgage_holders, policy_territory, separation_of_insureds, other \u2014 REQUIRED
+- content: full verbatim condition text \u2014 REQUIRED
+- keyValues: extract specific values as key-value pairs (e.g. noticePeriod: "30 days", suitDeadline: "2 years")
+- pageNumber: page number where the condition appears
+
 Focus on:
 - Duties after loss / notice of occurrence conditions
-- Cooperation clause
-- Cancellation and nonrenewal conditions (extract notice period in days)
-- Subrogation / transfer of rights
+- Notice requirements (extract notice period as keyValue)
+- Cancellation and nonrenewal conditions (extract notice period in days as keyValue)
 - Other insurance clause
+- Subrogation / transfer of rights
 - Examination under oath
 - Arbitration or appraisal provisions
 - Suit against us / legal action conditions
 - Liberalization clause
+- Concealment or fraud clause
+- Loss payment conditions
+- Mortgage holders clause
 - Any other named conditions
 
-For cancellation and nonrenewal conditions, extract the specific notice period in days if stated.
-
 Return JSON only.`;
 }
 
@@ -3227,12 +3361,16 @@ function createExtractor(config) {
         },
         {
           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,