@claritylabs/cl-sdk 3.1.3 → 3.1.4

package/dist/index.mjs

@@ -546,6 +546,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 +561,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 +571,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 +618,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 +690,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 +757,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 +765,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 +1476,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 +4657,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 +4688,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 +7673,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 +7702,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 +7721,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 +8185,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 +8192,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 +8209,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 +8220,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.
@@ -11432,6 +11436,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 +11451,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 +11505,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 +17192,11 @@ export {
   ScheduledItemCategorySchema,
   SectionSchema,
   SharedLimitSchema,
+  SourceBackedAddressSchema,
   SourceBackedValueSchema,
   SourceChunkSchema,
   SourceKindSchema,
+  SourceProvenanceSchema,
   SourceSpanBBoxSchema,
   SourceSpanKindSchema,
   SourceSpanLocationSchema,