@claritylabs/cl-sdk 3.1.3 → 3.1.4

package/dist/index.js

@@ -237,9 +237,11 @@ __export(src_exports, {
   ScheduledItemCategorySchema: () => ScheduledItemCategorySchema,
   SectionSchema: () => SectionSchema,
   SharedLimitSchema: () => SharedLimitSchema,
+  SourceBackedAddressSchema: () => SourceBackedAddressSchema,
   SourceBackedValueSchema: () => SourceBackedValueSchema,
   SourceChunkSchema: () => SourceChunkSchema,
   SourceKindSchema: () => SourceKindSchema,
+  SourceProvenanceSchema: () => SourceProvenanceSchema,
   SourceSpanBBoxSchema: () => SourceSpanBBoxSchema,
   SourceSpanKindSchema: () => SourceSpanKindSchema,
   SourceSpanLocationSchema: () => SourceSpanLocationSchema,
@@ -922,6 +924,13 @@ var PET_SPECIES = PetSpeciesSchema.options;
 
 // src/schemas/shared.ts
 var import_zod3 = require("zod");
+var SourceProvenanceSchema = import_zod3.z.object({
+  sourceSpanIds: import_zod3.z.array(import_zod3.z.string().min(1)).min(1),
+  documentNodeId: import_zod3.z.string().optional(),
+  sourceTextHash: import_zod3.z.string().optional(),
+  pageStart: import_zod3.z.number().int().positive().optional(),
+  pageEnd: import_zod3.z.number().int().positive().optional()
+});
 var AddressSchema = import_zod3.z.object({
   street1: import_zod3.z.string(),
   street2: import_zod3.z.string().optional(),
@@ -930,6 +939,7 @@ var AddressSchema = import_zod3.z.object({
   zip: import_zod3.z.string(),
   country: import_zod3.z.string().optional()
 });
+var SourceBackedAddressSchema = AddressSchema.merge(SourceProvenanceSchema);
 var ContactSchema = import_zod3.z.object({
   name: import_zod3.z.string().optional(),
   title: import_zod3.z.string().optional(),
@@ -939,7 +949,7 @@ var ContactSchema = import_zod3.z.object({
   email: import_zod3.z.string().optional(),
   address: AddressSchema.optional(),
   hours: import_zod3.z.string().optional()
-});
+}).merge(SourceProvenanceSchema);
 var FormReferenceSchema = import_zod3.z.object({
   formNumber: import_zod3.z.string(),
   editionDate: import_zod3.z.string().optional(),
@@ -986,7 +996,7 @@ var NamedInsuredSchema = import_zod3.z.object({
   name: import_zod3.z.string(),
   relationship: import_zod3.z.string().optional(),
   address: AddressSchema.optional()
-});
+}).merge(SourceProvenanceSchema);
 
 // src/schemas/coverage.ts
 var import_zod4 = require("zod");
@@ -1058,7 +1068,7 @@ var EndorsementPartySchema = import_zod5.z.object({
   address: AddressSchema.optional(),
   relationship: import_zod5.z.string().optional(),
   scope: import_zod5.z.string().optional()
-});
+}).merge(SourceProvenanceSchema);
 var EndorsementSchema = import_zod5.z.object({
   formNumber: import_zod5.z.string(),
   editionDate: import_zod5.z.string().optional(),
@@ -1125,7 +1135,7 @@ var InsurerInfoSchema = import_zod8.z.object({
   amBestNumber: import_zod8.z.string().optional(),
   admittedStatus: AdmittedStatusSchema.optional(),
   stateOfDomicile: import_zod8.z.string().optional()
-});
+}).merge(SourceProvenanceSchema);
 var ProducerInfoSchema = import_zod8.z.object({
   agencyName: import_zod8.z.string(),
   contactName: import_zod8.z.string().optional(),
@@ -1133,7 +1143,7 @@ var ProducerInfoSchema = import_zod8.z.object({
   phone: import_zod8.z.string().optional(),
   email: import_zod8.z.string().optional(),
   address: AddressSchema.optional()
-});
+}).merge(SourceProvenanceSchema);
 
 // src/schemas/financial.ts
 var import_zod9 = require("zod");
@@ -1844,7 +1854,7 @@ var BaseDocumentFields = {
   isRenewal: import_zod16.z.boolean().optional(),
   isPackage: import_zod16.z.boolean().optional(),
   insuredDba: import_zod16.z.string().optional(),
-  insuredAddress: AddressSchema.optional(),
+  insuredAddress: SourceBackedAddressSchema.optional(),
   insuredEntityType: EntityTypeSchema.optional(),
   additionalNamedInsureds: import_zod16.z.array(NamedInsuredSchema).optional(),
   insuredSicCode: import_zod16.z.string().optional(),
@@ -5017,6 +5027,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;
 }
@@ -5037,36 +5058,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
     };
   }
 }
@@ -8020,16 +8043,19 @@ Return JSON only.`;
 
 // src/prompts/extractors/named-insured.ts
 var import_zod27 = require("zod");
-var AddressSchema2 = import_zod27.z.object({
-  street1: import_zod27.z.string(),
-  city: import_zod27.z.string(),
-  state: import_zod27.z.string(),
-  zip: import_zod27.z.string()
-});
+var AdditionalNamedInsuredSchema = import_zod27.z.object({
+  name: import_zod27.z.string(),
+  relationship: import_zod27.z.string().optional().describe("e.g. subsidiary, affiliate"),
+  address: SourceBackedAddressSchema.optional()
+}).merge(SourceProvenanceSchema);
+var ScheduledPartySchema = import_zod27.z.object({
+  name: import_zod27.z.string(),
+  address: SourceBackedAddressSchema.optional()
+}).merge(SourceProvenanceSchema);
 var NamedInsuredSchema2 = import_zod27.z.object({
   insuredName: import_zod27.z.string().describe("Name of primary named insured"),
   insuredDba: import_zod27.z.string().optional().describe("Doing-business-as name"),
-  insuredAddress: AddressSchema2.optional().describe("Primary insured mailing address"),
+  insuredAddress: SourceBackedAddressSchema.optional().describe("Primary insured mailing address"),
   insuredEntityType: import_zod27.z.enum([
     "corporation",
     "llc",
@@ -8046,25 +8072,9 @@ var NamedInsuredSchema2 = import_zod27.z.object({
   insuredFein: import_zod27.z.string().optional().describe("Federal Employer Identification Number"),
   insuredSicCode: import_zod27.z.string().optional().describe("SIC code"),
   insuredNaicsCode: import_zod27.z.string().optional().describe("NAICS code"),
-  additionalNamedInsureds: import_zod27.z.array(
-    import_zod27.z.object({
-      name: import_zod27.z.string(),
-      relationship: import_zod27.z.string().optional().describe("e.g. subsidiary, affiliate"),
-      address: AddressSchema2.optional()
-    })
-  ).optional().describe("Additional named insureds listed on the policy"),
-  lossPayees: import_zod27.z.array(
-    import_zod27.z.object({
-      name: import_zod27.z.string(),
-      address: AddressSchema2.optional()
-    })
-  ).optional().describe("Loss payees listed on the policy"),
-  mortgageHolders: import_zod27.z.array(
-    import_zod27.z.object({
-      name: import_zod27.z.string(),
-      address: AddressSchema2.optional()
-    })
-  ).optional().describe("Mortgage holders / lienholders listed on the policy")
+  additionalNamedInsureds: import_zod27.z.array(AdditionalNamedInsuredSchema).optional().describe("Additional named insureds listed on the policy"),
+  lossPayees: import_zod27.z.array(ScheduledPartySchema).optional().describe("Loss payees listed on the policy"),
+  mortgageHolders: import_zod27.z.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.
@@ -8081,6 +8091,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.
@@ -8544,13 +8555,6 @@ Return JSON only.`;
 
 // src/prompts/extractors/supplementary.ts
 var import_zod36 = require("zod");
-var ContactSchema2 = import_zod36.z.object({
-  name: import_zod36.z.string().optional().describe("Organization or person name"),
-  phone: import_zod36.z.string().optional().describe("Phone number"),
-  email: import_zod36.z.string().optional().describe("Email address"),
-  address: import_zod36.z.string().optional().describe("Mailing address"),
-  type: import_zod36.z.string().optional().describe("Contact type, e.g. 'State Department of Insurance'")
-});
 var AuxiliaryFactSchema2 = import_zod36.z.object({
   key: import_zod36.z.string().describe("Normalized machine-readable fact key, e.g. 'policyholder_age' or 'insured_name'"),
   value: import_zod36.z.string().describe("Concrete extracted fact value"),
@@ -8558,9 +8562,9 @@ var AuxiliaryFactSchema2 = import_zod36.z.object({
   context: import_zod36.z.string().optional().describe("Short disambiguating context, such as 'Driver Schedule' or 'Named Insured'")
 });
 var SupplementarySchema = import_zod36.z.object({
-  regulatoryContacts: import_zod36.z.array(ContactSchema2).optional().describe("Regulatory body contacts (state department of insurance, ombudsman)"),
-  claimsContacts: import_zod36.z.array(ContactSchema2).optional().describe("Claims reporting contacts and instructions"),
-  thirdPartyAdministrators: import_zod36.z.array(ContactSchema2).optional().describe("Third-party administrators for claims handling"),
+  regulatoryContacts: import_zod36.z.array(ContactSchema).optional().describe("Regulatory body contacts (state department of insurance, ombudsman)"),
+  claimsContacts: import_zod36.z.array(ContactSchema).optional().describe("Claims reporting contacts and instructions"),
+  thirdPartyAdministrators: import_zod36.z.array(ContactSchema).optional().describe("Third-party administrators for claims handling"),
   cancellationNoticeDays: import_zod36.z.number().optional().describe("Required notice period for cancellation in days"),
   nonrenewalNoticeDays: import_zod36.z.number().optional().describe("Required notice period for nonrenewal in days"),
   auxiliaryFacts: import_zod36.z.array(AuxiliaryFactSchema2).optional().describe("Additional retrieval-only facts that do not fit the strict primary schema")
@@ -8575,7 +8579,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
@@ -8586,6 +8590,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.
@@ -11800,6 +11806,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";
@@ -11808,6 +11821,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,
@@ -11859,6 +11875,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,
@@ -17542,9 +17563,11 @@ var AGENT_TOOLS = [
   ScheduledItemCategorySchema,
   SectionSchema,
   SharedLimitSchema,
+  SourceBackedAddressSchema,
   SourceBackedValueSchema,
   SourceChunkSchema,
   SourceKindSchema,
+  SourceProvenanceSchema,
   SourceSpanBBoxSchema,
   SourceSpanKindSchema,
   SourceSpanLocationSchema,