@claritylabs/cl-sdk 3.1.3 → 3.1.5

package/dist/index.mjs

@@ -80,53 +80,70 @@ function sanitizeNulls(obj) {
 
 // src/core/strict-schema.ts
 import { z } from "zod";
+function schemaDef(schema) {
+  return schema._zod?.def ?? schema._def ?? {};
+}
+function schemaKind(schema) {
+  const def = schemaDef(schema);
+  const raw = typeof def.type === "string" ? def.type : typeof def.typeName === "string" ? def.typeName : typeof schema.type === "string" ? schema.type : void 0;
+  return raw?.replace(/^Zod/, "").toLowerCase();
+}
+function schemaDescription(schema) {
+  const def = schemaDef(schema);
+  return schema.description ?? def.description;
+}
+function objectShape(schema) {
+  const def = schemaDef(schema);
+  const shape = schema.shape ?? def.shape;
+  return typeof shape === "function" ? shape() : shape;
+}
+function withDescription(schema, description) {
+  return description ? schema.describe(description) : schema;
+}
 function toStrictSchema(schema) {
-  const def = schema._zod?.def;
-  const typeName = def?.type ?? schema.type;
-  if (typeName === "object") {
-    const shape = schema.shape;
+  const kind = schemaKind(schema);
+  const def = schemaDef(schema);
+  if (kind === "object") {
+    const shape = objectShape(schema);
     if (!shape) return schema;
     const newShape = {};
     for (const [key, value] of Object.entries(shape)) {
       const field = value;
-      const fieldDef = field._zod?.def;
-      const fieldType = fieldDef?.type ?? field.type;
-      if (fieldType === "optional") {
+      const fieldDef = schemaDef(field);
+      const fieldKind = schemaKind(field);
+      if (fieldKind === "optional") {
         const innerType = fieldDef?.innerType;
-        const description = field.description ?? fieldDef?.description ?? field._zod?.def?.description;
+        const description = schemaDescription(field);
         if (innerType) {
           const transformed = toStrictSchema(innerType);
-          let nullable = z.nullable(transformed);
-          if (description) nullable = nullable.describe(description);
-          newShape[key] = nullable;
+          newShape[key] = withDescription(z.nullable(transformed), description);
         } else {
-          let nullable = z.nullable(field);
-          if (description) nullable = nullable.describe(description);
-          newShape[key] = nullable;
+          newShape[key] = withDescription(z.nullable(field), description);
         }
       } else {
         newShape[key] = toStrictSchema(field);
       }
     }
-    const objDesc = schema.description ?? def?.description ?? schema._zod?.def?.description;
-    const result = z.object(newShape);
-    return objDesc ? result.describe(objDesc) : result;
+    return withDescription(z.object(newShape), schemaDescription(schema));
   }
-  if (typeName === "array") {
-    const element = def?.element ?? schema.element;
+  if (kind === "array") {
+    const element = def.element ?? def.type ?? schema.element;
     if (element) {
-      const arrDesc = schema.description ?? def?.description ?? schema._zod?.def?.description;
-      const result = z.array(toStrictSchema(element));
-      return arrDesc ? result.describe(arrDesc) : result;
+      return withDescription(z.array(toStrictSchema(element)), schemaDescription(schema));
+    }
+    return schema;
+  }
+  if (kind === "nullable") {
+    const innerType = def?.innerType;
+    if (innerType) {
+      return withDescription(z.nullable(toStrictSchema(innerType)), schemaDescription(schema));
     }
     return schema;
   }
-  if (typeName === "nullable") {
+  if (kind === "default") {
     const innerType = def?.innerType;
     if (innerType) {
-      const nullDesc = schema.description ?? def?.description ?? schema._zod?.def?.description;
-      const result = z.nullable(toStrictSchema(innerType));
-      return nullDesc ? result.describe(nullDesc) : result;
+      return withDescription(z.nullable(toStrictSchema(innerType)), schemaDescription(schema));
     }
     return schema;
   }
@@ -546,6 +563,13 @@ var PET_SPECIES = PetSpeciesSchema.options;
 
 // src/schemas/shared.ts
 import { z as z3 } from "zod";
+var SourceProvenanceSchema = z3.object({
+  sourceSpanIds: z3.array(z3.string().min(1)).min(1),
+  documentNodeId: z3.string().optional(),
+  sourceTextHash: z3.string().optional(),
+  pageStart: z3.number().int().positive().optional(),
+  pageEnd: z3.number().int().positive().optional()
+});
 var AddressSchema = z3.object({
   street1: z3.string(),
   street2: z3.string().optional(),
@@ -554,6 +578,7 @@ var AddressSchema = z3.object({
   zip: z3.string(),
   country: z3.string().optional()
 });
+var SourceBackedAddressSchema = AddressSchema.merge(SourceProvenanceSchema);
 var ContactSchema = z3.object({
   name: z3.string().optional(),
   title: z3.string().optional(),
@@ -563,7 +588,7 @@ var ContactSchema = z3.object({
   email: z3.string().optional(),
   address: AddressSchema.optional(),
   hours: z3.string().optional()
-});
+}).merge(SourceProvenanceSchema);
 var FormReferenceSchema = z3.object({
   formNumber: z3.string(),
   editionDate: z3.string().optional(),
@@ -610,7 +635,7 @@ var NamedInsuredSchema = z3.object({
   name: z3.string(),
   relationship: z3.string().optional(),
   address: AddressSchema.optional()
-});
+}).merge(SourceProvenanceSchema);
 
 // src/schemas/coverage.ts
 import { z as z4 } from "zod";
@@ -682,7 +707,7 @@ var EndorsementPartySchema = z5.object({
   address: AddressSchema.optional(),
   relationship: z5.string().optional(),
   scope: z5.string().optional()
-});
+}).merge(SourceProvenanceSchema);
 var EndorsementSchema = z5.object({
   formNumber: z5.string(),
   editionDate: z5.string().optional(),
@@ -749,7 +774,7 @@ var InsurerInfoSchema = z8.object({
   amBestNumber: z8.string().optional(),
   admittedStatus: AdmittedStatusSchema.optional(),
   stateOfDomicile: z8.string().optional()
-});
+}).merge(SourceProvenanceSchema);
 var ProducerInfoSchema = z8.object({
   agencyName: z8.string(),
   contactName: z8.string().optional(),
@@ -757,7 +782,7 @@ var ProducerInfoSchema = z8.object({
   phone: z8.string().optional(),
   email: z8.string().optional(),
   address: AddressSchema.optional()
-});
+}).merge(SourceProvenanceSchema);
 
 // src/schemas/financial.ts
 import { z as z9 } from "zod";
@@ -1468,7 +1493,7 @@ var BaseDocumentFields = {
   isRenewal: z16.boolean().optional(),
   isPackage: z16.boolean().optional(),
   insuredDba: z16.string().optional(),
-  insuredAddress: AddressSchema.optional(),
+  insuredAddress: SourceBackedAddressSchema.optional(),
   insuredEntityType: EntityTypeSchema.optional(),
   additionalNamedInsureds: z16.array(NamedInsuredSchema).optional(),
   insuredSicCode: z16.string().optional(),
@@ -4649,6 +4674,17 @@ function getCoveredReasons(memory) {
 }
 
 // src/extraction/promote.ts
+function sourceProvenance(raw) {
+  const sourceSpanIds = Array.isArray(raw.sourceSpanIds) ? raw.sourceSpanIds.filter((id) => typeof id === "string" && id.trim().length > 0) : [];
+  if (sourceSpanIds.length === 0) return void 0;
+  return {
+    sourceSpanIds,
+    ...typeof raw.documentNodeId === "string" ? { documentNodeId: raw.documentNodeId } : {},
+    ...typeof raw.sourceTextHash === "string" ? { sourceTextHash: raw.sourceTextHash } : {},
+    ...typeof raw.pageStart === "number" ? { pageStart: raw.pageStart } : {},
+    ...typeof raw.pageEnd === "number" ? { pageEnd: raw.pageEnd } : {}
+  };
+}
 function stringValue(value) {
   return typeof value === "string" && value.trim() ? value : void 0;
 }
@@ -4669,36 +4705,38 @@ function promoteRawFields(raw, mappings) {
 }
 function promoteCarrierFields(doc) {
   const raw = doc;
+  const provenance = sourceProvenance(raw);
   promoteRawFields(raw, [
     { from: "naicNumber", to: "carrierNaicNumber" },
     { from: "amBestRating", to: "carrierAmBestRating" },
     { from: "admittedStatus", to: "carrierAdmittedStatus" }
   ]);
-  if (!raw.insurer && raw.carrierLegalName) {
+  if (!raw.insurer && raw.carrierLegalName && provenance) {
     raw.insurer = {
       legalName: raw.carrierLegalName,
       ...raw.carrierNaicNumber ? { naicNumber: raw.carrierNaicNumber } : {},
       ...raw.carrierAmBestRating ? { amBestRating: raw.carrierAmBestRating } : {},
-      ...raw.carrierAdmittedStatus ? { admittedStatus: raw.carrierAdmittedStatus } : {}
+      ...raw.carrierAdmittedStatus ? { admittedStatus: raw.carrierAdmittedStatus } : {},
+      ...provenance
     };
   }
 }
 function promoteBroker(doc) {
   const raw = doc;
+  const provenance = sourceProvenance(raw);
   const brokerAgency = findRawString(raw, ["brokerAgency"]);
   const brokerContact = findRawString(raw, ["brokerContactName"]);
   const brokerLicense = findRawString(raw, ["brokerLicenseNumber"]);
   const brokerPhone = findRawString(raw, ["brokerPhone"]);
   const brokerEmail = findRawString(raw, ["brokerEmail"]);
-  const brokerAddress = findRawString(raw, ["brokerAddress"]);
-  if (!raw.producer && brokerAgency) {
+  if (!raw.producer && brokerAgency && provenance) {
     raw.producer = {
       agencyName: brokerAgency,
       ...brokerContact ? { contactName: brokerContact } : {},
       ...brokerLicense ? { licenseNumber: brokerLicense } : {},
       ...brokerPhone ? { phone: brokerPhone } : {},
       ...brokerEmail ? { email: brokerEmail } : {},
-      ...brokerAddress ? { address: { street1: brokerAddress } } : {}
+      ...provenance
     };
   }
 }
@@ -7652,16 +7690,19 @@ Return JSON only.`;
 
 // src/prompts/extractors/named-insured.ts
 import { z as z27 } from "zod";
-var AddressSchema2 = z27.object({
-  street1: z27.string(),
-  city: z27.string(),
-  state: z27.string(),
-  zip: z27.string()
-});
+var AdditionalNamedInsuredSchema = z27.object({
+  name: z27.string(),
+  relationship: z27.string().optional().describe("e.g. subsidiary, affiliate"),
+  address: SourceBackedAddressSchema.optional()
+}).merge(SourceProvenanceSchema);
+var ScheduledPartySchema = z27.object({
+  name: z27.string(),
+  address: SourceBackedAddressSchema.optional()
+}).merge(SourceProvenanceSchema);
 var NamedInsuredSchema2 = z27.object({
   insuredName: z27.string().describe("Name of primary named insured"),
   insuredDba: z27.string().optional().describe("Doing-business-as name"),
-  insuredAddress: AddressSchema2.optional().describe("Primary insured mailing address"),
+  insuredAddress: SourceBackedAddressSchema.optional().describe("Primary insured mailing address"),
   insuredEntityType: z27.enum([
     "corporation",
     "llc",
@@ -7678,25 +7719,9 @@ var NamedInsuredSchema2 = z27.object({
   insuredFein: z27.string().optional().describe("Federal Employer Identification Number"),
   insuredSicCode: z27.string().optional().describe("SIC code"),
   insuredNaicsCode: z27.string().optional().describe("NAICS code"),
-  additionalNamedInsureds: z27.array(
-    z27.object({
-      name: z27.string(),
-      relationship: z27.string().optional().describe("e.g. subsidiary, affiliate"),
-      address: AddressSchema2.optional()
-    })
-  ).optional().describe("Additional named insureds listed on the policy"),
-  lossPayees: z27.array(
-    z27.object({
-      name: z27.string(),
-      address: AddressSchema2.optional()
-    })
-  ).optional().describe("Loss payees listed on the policy"),
-  mortgageHolders: z27.array(
-    z27.object({
-      name: z27.string(),
-      address: AddressSchema2.optional()
-    })
-  ).optional().describe("Mortgage holders / lienholders listed on the policy")
+  additionalNamedInsureds: z27.array(AdditionalNamedInsuredSchema).optional().describe("Additional named insureds listed on the policy"),
+  lossPayees: z27.array(ScheduledPartySchema).optional().describe("Loss payees listed on the policy"),
+  mortgageHolders: z27.array(ScheduledPartySchema).optional().describe("Mortgage holders / lienholders listed on the policy")
 });
 function buildNamedInsuredPrompt() {
   return `You are an expert insurance document analyst. Extract all named insured information from this document.
@@ -7713,6 +7738,7 @@ Focus on:
 Look on the declarations page, named insured schedule, loss payee schedule, mortgagee schedule, and any endorsements that add or modify named insureds, loss payees, or mortgage holders.
 
 Critical rules:
+- Every insuredAddress, additionalNamedInsureds row, lossPayees row, and mortgageHolders row must include sourceSpanIds from the source evidence. Omit the row if source spans are unavailable.
 - Prefer declaration-table labels such as "Named Insured", "Named Insured and Address", "Applicant", or "Insured" over contact blocks, notice contacts, authorized officers, licensing statements, signatures, and corporate-authority wording.
 - Do not use an authorized officer, broker, producer, contact person, officer title, email address owner, or licensing/entity-status statement as the primary insured unless that exact person/entity is explicitly labeled as the named insured.
 - If a row combines the insured name with a mailing address, put the legal name in insuredName and the mailing address in insuredAddress.
@@ -8176,13 +8202,6 @@ Return JSON only.`;
 
 // src/prompts/extractors/supplementary.ts
 import { z as z36 } from "zod";
-var ContactSchema2 = z36.object({
-  name: z36.string().optional().describe("Organization or person name"),
-  phone: z36.string().optional().describe("Phone number"),
-  email: z36.string().optional().describe("Email address"),
-  address: z36.string().optional().describe("Mailing address"),
-  type: z36.string().optional().describe("Contact type, e.g. 'State Department of Insurance'")
-});
 var AuxiliaryFactSchema2 = z36.object({
   key: z36.string().describe("Normalized machine-readable fact key, e.g. 'policyholder_age' or 'insured_name'"),
   value: z36.string().describe("Concrete extracted fact value"),
@@ -8190,9 +8209,9 @@ var AuxiliaryFactSchema2 = z36.object({
   context: z36.string().optional().describe("Short disambiguating context, such as 'Driver Schedule' or 'Named Insured'")
 });
 var SupplementarySchema = z36.object({
-  regulatoryContacts: z36.array(ContactSchema2).optional().describe("Regulatory body contacts (state department of insurance, ombudsman)"),
-  claimsContacts: z36.array(ContactSchema2).optional().describe("Claims reporting contacts and instructions"),
-  thirdPartyAdministrators: z36.array(ContactSchema2).optional().describe("Third-party administrators for claims handling"),
+  regulatoryContacts: z36.array(ContactSchema).optional().describe("Regulatory body contacts (state department of insurance, ombudsman)"),
+  claimsContacts: z36.array(ContactSchema).optional().describe("Claims reporting contacts and instructions"),
+  thirdPartyAdministrators: z36.array(ContactSchema).optional().describe("Third-party administrators for claims handling"),
   cancellationNoticeDays: z36.number().optional().describe("Required notice period for cancellation in days"),
   nonrenewalNoticeDays: z36.number().optional().describe("Required notice period for nonrenewal in days"),
   auxiliaryFacts: z36.array(AuxiliaryFactSchema2).optional().describe("Additional retrieval-only facts that do not fit the strict primary schema")
@@ -8207,7 +8226,7 @@ ${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
+- Regulatory contacts: state department of insurance, regulatory bodies, ombudsman offices \u2014 with phone, email, structured address
 - Claims contacts: how to report claims, claims department contact info, hours of operation
 - Third-party administrators (TPAs) for claims handling
 - Cancellation notice period in days
@@ -8218,6 +8237,8 @@ Focus on:
 
 Look for regulatory notices, complaint contact sections, claims reporting instructions, and cancellation/nonrenewal provisions throughout the document.
 
+Every regulatoryContacts, claimsContacts, and thirdPartyAdministrators row must include sourceSpanIds from the source evidence. Omit contacts when source spans are unavailable.
+
 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.
@@ -9845,6 +9866,8 @@ Rules:
 - Keep a coverage when it is a real operational coverage/benefit even if only one term needs cleanup.
 - When changing a term's semantic meaning, set kind to the corrected normalized term kind.
 - Do not add new coverage rows or new terms; this pass cleans the existing projection.
+- Include every JSON key in each decision. Use null for scalar fields you are not changing and [] for source ID lists you are not changing.
+- For each coverage decision, always include termDecisions. Use [] when no terms need cleanup.
 - Keep reasons concise and factual.
 
 Candidate projection:
@@ -9855,9 +9878,6 @@ ${JSON.stringify(nodes, null, 2)}
 
 Return JSON with coverageDecisions and warnings only.`;
 }
-function hasOwn(object, key) {
-  return Object.prototype.hasOwnProperty.call(object, key);
-}
 function uniqueStrings(values) {
   return [...new Set(values.filter((value) => value.length > 0))];
 }
@@ -9932,18 +9952,16 @@ function applyTermCleanupDecision(term, decision, validNodeIds, validSpanIds) {
     sourceSpanIds: cleanupIds(decision.sourceSpanIds, validSpanIds, term.sourceSpanIds)
   };
   if (next.sourceNodeIds.length === 0 && next.sourceSpanIds.length === 0) return term;
-  if (hasOwn(decision, "amount")) {
-    if (typeof decision.amount === "number" && Number.isFinite(decision.amount)) next.amount = decision.amount;
-    else delete next.amount;
+  if (typeof decision.amount === "number" && Number.isFinite(decision.amount)) {
+    next.amount = decision.amount;
   } else if (decision.value || decision.kind) {
     const amount = next.kind === "retroactive_date" ? void 0 : amountFromOperationalValue(next.value);
     if (amount === void 0) delete next.amount;
     else next.amount = amount;
   }
-  if (hasOwn(decision, "appliesTo")) {
+  if (decision.appliesTo != null) {
     const appliesTo = cleanProfileValue(decision.appliesTo);
     if (appliesTo) next.appliesTo = appliesTo;
-    else delete next.appliesTo;
   }
   return next;
 }
@@ -9962,46 +9980,42 @@ function applyCoverageCleanupDecision(coverage, decision, validNodeIds, validSpa
   const name = cleanProfileValue(decision.name);
   if (name) next.name = name;
   if (decision.coverageOrigin) next.coverageOrigin = decision.coverageOrigin;
-  if (hasOwn(decision, "limit")) {
+  if (decision.limit != null) {
     const value = cleanProfileValue(decision.limit);
     if (value) next.limit = value;
-    else delete next.limit;
   }
-  if (hasOwn(decision, "deductible")) {
+  if (decision.deductible != null) {
     const value = cleanProfileValue(decision.deductible);
     if (value) next.deductible = value;
-    else delete next.deductible;
   }
-  if (hasOwn(decision, "premium")) {
+  if (decision.premium != null) {
     const value = cleanProfileValue(decision.premium);
     if (value) next.premium = value;
-    else delete next.premium;
   }
-  if (hasOwn(decision, "retroactiveDate")) {
+  if (decision.retroactiveDate != null) {
     const value = cleanProfileValue(decision.retroactiveDate);
     if (value) next.retroactiveDate = value;
-    else delete next.retroactiveDate;
   }
   const termDecisions = (decision.termDecisions ?? []).filter((termDecision) => termDecision.termIndex < coverage.limits.length);
   const termDecisionByIndex = new Map(termDecisions.map((termDecision) => [termDecision.termIndex, termDecision]));
   next.limits = coverage.limits.map((term, index) => applyTermCleanupDecision(term, termDecisionByIndex.get(index), validNodeIds, validSpanIds)).filter((term) => Boolean(term));
   if (termDecisions.length > 0) {
-    if (!hasOwn(decision, "limit") && termDecisionsTouch(coverage, termDecisions, isLimitTerm)) {
+    if (decision.limit == null && termDecisionsTouch(coverage, termDecisions, isLimitTerm)) {
       const value = primaryLimitFromTerms(next.limits);
       if (value) next.limit = value;
       else delete next.limit;
     }
-    if (!hasOwn(decision, "deductible") && termDecisionsTouch(coverage, termDecisions, isDeductibleTerm)) {
+    if (decision.deductible == null && termDecisionsTouch(coverage, termDecisions, isDeductibleTerm)) {
       const value = deductibleFromTerms(next.limits);
       if (value) next.deductible = value;
       else delete next.deductible;
     }
-    if (!hasOwn(decision, "premium") && termDecisionsTouch(coverage, termDecisions, isPremiumTerm)) {
+    if (decision.premium == null && termDecisionsTouch(coverage, termDecisions, isPremiumTerm)) {
       const value = premiumFromTerms(next.limits);
       if (value) next.premium = value;
       else delete next.premium;
     }
-    if (!hasOwn(decision, "retroactiveDate") && termDecisionsTouch(coverage, termDecisions, isRetroactiveDateTerm)) {
+    if (decision.retroactiveDate == null && termDecisionsTouch(coverage, termDecisions, isRetroactiveDateTerm)) {
       const value = retroactiveDateFromTerms(next.limits);
       if (value) next.retroactiveDate = value;
       else delete next.retroactiveDate;
@@ -11432,6 +11446,13 @@ function valueOf(profile, key) {
   }
   return String(value.value);
 }
+function provenanceOf(value) {
+  if (!value?.sourceSpanIds.length) return void 0;
+  return {
+    sourceSpanIds: value.sourceSpanIds,
+    ...value.sourceNodeIds[0] ? { documentNodeId: value.sourceNodeIds[0] } : {}
+  };
+}
 function materializeDocument(params) {
   const profile = params.operationalProfile;
   const policyNumber = valueOf(profile, "policyNumber") ?? "Unknown";
@@ -11440,6 +11461,9 @@ function materializeDocument(params) {
   const effectiveDate = valueOf(profile, "effectiveDate") ?? "Unknown";
   const expirationDate = valueOf(profile, "expirationDate") ?? "Unknown";
   const premium = valueOf(profile, "premium");
+  const insurerProvenance = provenanceOf(profile.insurer);
+  const broker = valueOf(profile, "broker");
+  const brokerProvenance = provenanceOf(profile.broker);
   const coverages = profile.coverages.map((coverage) => ({
     name: coverage.name,
     coverageCode: coverage.coverageCode,
@@ -11491,6 +11515,11 @@ function materializeDocument(params) {
     security: carrier,
     insuredName,
     premium,
+    ...insurerProvenance ? { insurer: { legalName: carrier, ...insurerProvenance } } : {},
+    ...broker && brokerProvenance ? {
+      brokerAgency: broker,
+      producer: { agencyName: broker, ...brokerProvenance }
+    } : {},
     policyTypes: profile.policyTypes,
     formInventory: params.formInventory.filter((form) => typeof form.formNumber === "string" && form.formNumber.trim().length > 0).map((form) => ({
       formNumber: form.formNumber,
@@ -17173,9 +17202,11 @@ export {
   ScheduledItemCategorySchema,
   SectionSchema,
   SharedLimitSchema,
+  SourceBackedAddressSchema,
   SourceBackedValueSchema,
   SourceChunkSchema,
   SourceKindSchema,
+  SourceProvenanceSchema,
   SourceSpanBBoxSchema,
   SourceSpanKindSchema,
   SourceSpanLocationSchema,