@claritylabs/cl-sdk 4.2.0 → 4.3.0

package/dist/index.mjs

@@ -1060,7 +1060,8 @@ var InsurerInfoSchema = z9.object({
   amBestRating: z9.string().optional(),
   amBestNumber: z9.string().optional(),
   admittedStatus: AdmittedStatusSchema.optional(),
-  stateOfDomicile: z9.string().optional()
+  stateOfDomicile: z9.string().optional(),
+  address: AddressSchema.optional()
 }).merge(SourceProvenanceSchema);
 var ProducerInfoSchema = z9.object({
   agencyName: z9.string(),
@@ -2432,6 +2433,7 @@ var OperationalCoverageLineSchema = z21.object({
 var OperationalPartySchema = z21.object({
   role: z21.string(),
   name: z21.string(),
+  address: OperationalAddressSchema.optional(),
   sourceNodeIds: z21.array(z21.string().min(1)).default([]),
   sourceSpanIds: z21.array(z21.string().min(1)).default([])
 });
@@ -2469,6 +2471,7 @@ var PolicyOperationalProfileSchema = z21.preprocess(
     expirationDate: SourceBackedValueSchema.optional(),
     retroactiveDate: SourceBackedValueSchema.optional(),
     premium: SourceBackedValueSchema.optional(),
+    operationsDescription: SourceBackedValueSchema.optional(),
     declarationFacts: z21.array(OperationalDeclarationFactSchema).default([]),
     coverages: z21.array(OperationalCoverageLineSchema).default([]),
     parties: z21.array(OperationalPartySchema).default([]),
@@ -3847,6 +3850,34 @@ function cleanCoverageLineOfBusiness(value) {
 function normalizedFactValue(value) {
   return value.toLowerCase().replace(/&/g, " and ").replace(/[.,#]/g, " ").replace(/\s+/g, " ").trim();
 }
+var OPERATIONAL_ADDRESS_FIELDS = [
+  "street1",
+  "street2",
+  "city",
+  "state",
+  "zip",
+  "country",
+  "formatted"
+];
+function normalizeOperationalAddress(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return void 0;
+  const record = value;
+  const address = Object.fromEntries(
+    OPERATIONAL_ADDRESS_FIELDS.flatMap((field) => {
+      const cleaned = typeof record[field] === "string" ? cleanValue(record[field]) : void 0;
+      return cleaned ? [[field, cleaned]] : [];
+    })
+  );
+  return Object.keys(address).length > 0 ? address : void 0;
+}
+function normalizeOperationalPartyRole(value) {
+  const normalized = value.toLowerCase().replace(/[\s-]+/g, "_");
+  if (normalized === "namedinsured" || normalized === "insured") return "named_insured";
+  if (normalized === "managing_general_agent") return "mga";
+  if (normalized === "managing_general_underwriter") return "mga";
+  if (normalized === "third_party_administrator") return "administrator";
+  return normalized;
+}
 var OPERATIONAL_COVERAGE_TERM_KINDS = /* @__PURE__ */ new Set([
   "each_claim_limit",
   "each_occurrence_limit",
@@ -3945,6 +3976,7 @@ function mergeOperationalProfile(base, candidate, validNodeIds, validSpanIds) {
   const expirationDate = mergeValue(base.expirationDate, candidate.expirationDate);
   const retroactiveDate = mergeValue(base.retroactiveDate, candidate.retroactiveDate);
   const premium = mergeValue(base.premium, candidate.premium);
+  const operationsDescription = mergeValue(base.operationsDescription, candidate.operationsDescription);
   const candidateDeclarationFacts = Array.isArray(candidate.declarationFacts) ? candidate.declarationFacts.map(mergeDeclarationFact).filter((fact) => Boolean(fact)) : [];
   const declarationFacts = [
     ...base.declarationFacts,
@@ -3969,7 +4001,8 @@ function mergeOperationalProfile(base, candidate, validNodeIds, validSpanIds) {
     effectiveDate,
     expirationDate,
     retroactiveDate,
-    premium
+    premium,
+    operationsDescription
   ].filter((value) => Boolean(value));
   const coverages = base.coverages.length > 0 ? base.coverages : Array.isArray(candidate.coverages) ? candidate.coverages.map((coverage) => {
     const record = coverage;
@@ -4028,14 +4061,21 @@ function mergeOperationalProfile(base, candidate, validNodeIds, validSpanIds) {
     const record = party;
     const role = typeof record.role === "string" ? cleanValue(record.role) : void 0;
     const name = typeof record.name === "string" ? cleanValue(record.name) : void 0;
+    const address = normalizeOperationalAddress(record.address);
     const sourceNodeIds2 = keepIds(record.sourceNodeIds, validNodeIds);
     const sourceSpanIds2 = keepIds(record.sourceSpanIds, validSpanIds);
     if (!role || !name || sourceNodeIds2.length === 0 && sourceSpanIds2.length === 0) return [];
-    return [{ role, name, sourceNodeIds: sourceNodeIds2, sourceSpanIds: sourceSpanIds2 }];
+    return [{
+      role: normalizeOperationalPartyRole(role),
+      name,
+      address,
+      sourceNodeIds: sourceNodeIds2,
+      sourceSpanIds: sourceSpanIds2
+    }];
   }) : [];
   const parties = [
-    ...base.parties,
     ...candidateParties,
+    ...base.parties,
     sourceBackedParty("named_insured", namedInsured),
     sourceBackedParty("insurer", insurer),
     sourceBackedParty("broker", broker)
@@ -4109,6 +4149,7 @@ function mergeOperationalProfile(base, candidate, validNodeIds, validSpanIds) {
     expirationDate,
     retroactiveDate,
     premium,
+    operationsDescription,
     declarationFacts,
     coverages: annotatedCoverages,
     parties,
@@ -4582,7 +4623,8 @@ function sourceIdsFromOperationalProfile(profile) {
     profile.effectiveDate,
     profile.expirationDate,
     profile.retroactiveDate,
-    profile.premium
+    profile.premium,
+    profile.operationsDescription
   ].filter(Boolean);
   return {
     sourceNodeIds: uniqueStrings([
@@ -4666,6 +4708,21 @@ var OperationalDeclarationFactForPromptSchema = z23.object({
   sourceNodeIds: z23.array(z23.string()),
   sourceSpanIds: z23.array(z23.string())
 });
+var OperationalPartyForPromptSchema = z23.object({
+  role: z23.enum([
+    "named_insured",
+    "producer",
+    "broker",
+    "insurer",
+    "carrier",
+    "mga",
+    "administrator"
+  ]),
+  name: z23.string(),
+  address: OperationalAddressForPromptSchema.optional(),
+  sourceNodeIds: z23.array(z23.string()),
+  sourceSpanIds: z23.array(z23.string())
+});
 var OperationalProfilePromptSchema = z23.object({
   documentType: z23.enum(["policy", "quote"]).optional(),
   linesOfBusiness: z23.array(z23.string()).optional(),
@@ -4677,7 +4734,9 @@ var OperationalProfilePromptSchema = z23.object({
   expirationDate: SourceBackedValueForPromptSchema.optional(),
   retroactiveDate: SourceBackedValueForPromptSchema.optional(),
   premium: SourceBackedValueForPromptSchema.optional(),
+  operationsDescription: SourceBackedValueForPromptSchema.optional(),
   declarationFacts: z23.array(OperationalDeclarationFactForPromptSchema).optional(),
+  parties: z23.array(OperationalPartyForPromptSchema).optional(),
   coverages: z23.array(z23.object({
     name: z23.string(),
     lineOfBusiness: z23.string().optional(),
@@ -5589,6 +5648,9 @@ function operationalEvidenceScore(span) {
   if (span.metadata?.elementType === "title") score += 4;
   if (span.sourceUnit === "page") score -= 3;
   if (/\b(policy\s*(number|period|term)|effective date|expiration date|expiry date|named insured|insurer|carrier|security|broker|producer|premium|total due)\b/i.test(text)) score += 12;
+  if (/\b(mailing address|business address|address|managing general (?:agent|underwriter)|mga|administrator|description of operations|operations description|nature of business|business description)\b/i.test(text)) score += 12;
+  if (/\b\d{1,6}\s+[A-Z0-9][^\n,]{1,80}\b(?:street|st|avenue|ave|road|rd|boulevard|blvd|drive|dr|lane|ln|way|court|ct|highway|hwy)\b/i.test(text)) score += 10;
+  if (/\b[A-Za-z][A-Za-z .'-]+,\s*[A-Z]{2}\s+\d{5}(?:-\d{4})?\b/.test(text)) score += 10;
   if (/\b(coverage part|limit(?:s)? of liability|deductible|retention|retroactive date|aggregate|sublimit|sub-limit|each claim|each loss|each occurrence|coinsurance)\b/i.test(text)) score += 14;
   if (/\bendorsement\s+(?:no\.?|number|#)?\s*[A-Z0-9]|forms? and endorsements?|attached at inception|schedule\b/i.test(text)) score += 8;
   if (/\bitem\s+\d+\.?\s*(?:named insured|policy number|policy period|renewal|form of business|coverage parts?|premium|extended reporting|producer|forms? and endorsements?)\b/i.test(text)) score += 10;
@@ -5608,10 +5670,13 @@ function isOperationalEvidenceAnchor(span) {
   const text = cleanText([span.text, span.formNumber].filter(Boolean).join(" "), "");
   if (!text) return false;
   if (sourceUnit3 === "page") {
-    return hasSubstantiveDeclarationsScheduleText(text) || /\b(declarations?|named insured|policy number|policy period|effective date|expiration date|premium|total due|producer)\b/i.test(text);
+    return hasSubstantiveDeclarationsScheduleText(text) || /\b(declarations?|named insured|policy number|policy period|effective date|expiration date|premium|total due|producer|mailing address|mga|administrator|description of operations|nature of business|business description)\b/i.test(text);
   }
   if (/\bitem\s+\d+\.?\s*(?:named insured|policy number|policy period|renewal|form of business|coverage parts?|premium|extended reporting|producer|forms? and endorsements?)\b/i.test(text)) return true;
   if (/\b(policy\s*(number|period)|effective date|expiration date|expiry date|named insured|insurer|carrier|broker|producer|premium|total due)\b/i.test(text)) return true;
+  if (/\b(mailing address|business address|address|managing general (?:agent|underwriter)|mga|administrator|description of operations|operations description|nature of business|business description)\b/i.test(text)) return true;
+  if (/\b\d{1,6}\s+[A-Z0-9][^\n,]{1,80}\b(?:street|st|avenue|ave|road|rd|boulevard|blvd|drive|dr|lane|ln|way|court|ct|highway|hwy)\b/i.test(text)) return true;
+  if (/\b[A-Za-z][A-Za-z .'-]+,\s*[A-Z]{2}\s+\d{5}(?:-\d{4})?\b/.test(text)) return true;
   if (/\b(coverage part|forms? and endorsements?|attached at inception|endorsement\s+(?:no\.?|number|#)?\s*[A-Z0-9])\b/i.test(text)) return true;
   if (/\$[\d,.]+|[0-9]{1,2}\/[0-9]{1,2}\/[0-9]{2,4}|[0-9]{1,2}\s+[A-Za-z]{3,9}\s+[0-9]{4}/.test(text)) return true;
   return false;
@@ -5629,6 +5694,7 @@ function operationalEvidencePages(sourceSpans) {
     if (/\bcoverage parts?,?\s+limits? of liability,?\s+deductibles?,?\s+and retroactive dates\b/i.test(text)) score += 24;
     if (/\b(policy\s*(number|period|term)|effective date|expiration date|expiry date|named insured|insurer|carrier|security)\b/i.test(text)) score += 12;
     if (/\b(premium|total due|tax|fee|producer|broker)\b/i.test(text)) score += 10;
+    if (/\b(mailing address|business address|managing general (?:agent|underwriter)|mga|administrator|description of operations|operations description|nature of business|business description)\b/i.test(text)) score += 16;
     if (/\b(endorsement\s+(?:no\.?|number|#)?\s*[A-Z0-9]|attached at inception|forms? and endorsements?)\b/i.test(text)) score += 8;
     if (/\b(definitions?|exclusions?|conditions?|duties in the event|action against|cancellation by)\b/i.test(text)) score -= 12;
     if (score > 0) scores.set(page, (scores.get(page) ?? 0) + score);
@@ -5703,7 +5769,7 @@ function operationalProfilePromptNodes(sourceTree) {
       return true;
     }
     const text = [node.title, node.path, node.description, node.textExcerpt].filter(Boolean).join(" ");
-    return /\b(policy\s*(number|period)|named insured|insurer|carrier|broker|producer|premium|coverage|limit|liability|deductible|retention|retroactive|aggregate|sublimit|sub-limit|endorsement)\b/i.test(text);
+    return /\b(policy\s*(number|period)|named insured|insurer|carrier|broker|producer|managing general (?:agent|underwriter)|mga|administrator|mailing address|description of operations|operations description|nature of business|business description|premium|coverage|limit|liability|deductible|retention|retroactive|aggregate|sublimit|sub-limit|endorsement)\b/i.test(text);
   }).slice(0, 420);
 }
 function emptyOperationalProfile() {
@@ -5727,7 +5793,8 @@ function buildOperationalProfilePrompt(sourceTree, sourceSpans) {
   return `Extract a source-backed operational profile for an insurance policy.
 
 Return only high-value operational facts needed for policy lists, Q&A, compliance, and certificate generation:
-- policy number, named insured, insurer/carrier/security, broker/producer, policy period, retroactive date, premium
+- policy number, named insured, insurer/carrier/security, broker/producer, policy period, retroactive date, premium, and the insured's description of operations
+- parties[] rows for named insured, producer/broker, insurer/carrier, and MGA/administrator identities and their mailing addresses
 - source-backed declarationFacts for named-insured identity details: named insured, mailing address, DBA, entity type, tax ID/FEIN, additional named insureds, and other durable declaration-page identity facts
 - coverage units with their own nested limit terms, deductibles/retentions, retroactive dates, premiums, and form references
 - coverage type labels
@@ -5739,6 +5806,9 @@ Rules:
 - If a value is not directly supported, omit it.
 - Prefer declarations, schedules, premium tables, and endorsement schedules over generic policy wording.
 - Put named-insured mailing address in declarationFacts[] with field "mailingAddress", valueKind "address", a user-facing value string, and structured address fields when present. Do not put producer, broker, insurer, mortgagee, loss-payee, or certificate-holder addresses in mailingAddress.
+- Put every source-backed policy party in parties[] using only these canonical roles: "named_insured", "producer", "broker", "insurer", "carrier", "mga", or "administrator". Keep producer/broker, insurer/carrier, and MGA/administrator addresses policy-scoped in parties[]; never represent them as the named-insured mailingAddress declaration fact.
+- When a party's address is present, return its available street1, street2, city, state, zip, country, and formatted parts under parties[].address. Partial addresses are allowed in parties[], but never guess a missing component. The party row must cite the source node or source span that supports both the identity and address.
+- Put the insured's directly stated business or operations description in operationsDescription. Do not synthesize it from coverages, industry inference, website research, or generic policy wording.
 - Put DBA or trade name in declarationFacts[] with field "dba"; entity/legal form in field "entityType"; FEIN/tax ID in field "taxId"; each additional named insured in field "additionalNamedInsured".
 - For effective, expiration, retroactive, and other date fields, return a normalized YYYY-MM-DD value when the source date is unambiguous, including month-name dates such as "20 Feb 2026". Do not emit fragmented date text such as "20 2 2026".
 - For broker/producer, extract the agency or company legal name, not the license role, credential, or type. In a block like "Bayshore Insurance Brokers, LLC" followed by "Surplus Lines Broker - CA License No. ...", broker.value must be "Bayshore Insurance Brokers, LLC"; the surplus-lines role and license number are not the broker name.
@@ -5808,13 +5878,6 @@ 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 provenanceFromIds(sourceSpanIds, sourceNodeIds) {
   if (sourceSpanIds.length === 0) return void 0;
   return {
@@ -5822,6 +5885,33 @@ function provenanceFromIds(sourceSpanIds, sourceNodeIds) {
     ...sourceNodeIds[0] ? { documentNodeId: sourceNodeIds[0] } : {}
   };
 }
+function combinedProvenance(...values) {
+  const sourceSpanIds = [...new Set(values.flatMap((value) => value?.sourceSpanIds ?? []))];
+  const sourceNodeIds = [...new Set(values.flatMap((value) => value?.sourceNodeIds ?? []))];
+  return provenanceFromIds(sourceSpanIds, sourceNodeIds);
+}
+function firstOperationalParty(profile, roles) {
+  const candidates = roles.flatMap(
+    (role) => profile.parties.filter((candidate) => candidate.role === role && candidate.name.trim())
+  );
+  return candidates.find((candidate) => candidate.address) ?? candidates[0];
+}
+function completeOperationalAddress(address) {
+  if (!address?.street1 || !address.city || !address.state || !address.zip) return void 0;
+  return {
+    street1: address.street1,
+    street2: address.street2,
+    city: address.city,
+    state: address.state,
+    zip: address.zip,
+    country: address.country
+  };
+}
+function sourceBackedAddressFromParty(party) {
+  const address = completeOperationalAddress(party?.address);
+  const provenance = party ? provenanceFromIds(party.sourceSpanIds, party.sourceNodeIds) : void 0;
+  return address && provenance ? { ...address, ...provenance } : void 0;
+}
 function declarationFactsByField(profile, field) {
   return profile.declarationFacts.filter((fact) => fact.field === field && fact.value.trim());
 }
@@ -5872,16 +5962,21 @@ function declarationFieldName(fact) {
 function materializeDocument(params) {
   const profile = params.operationalProfile;
   const policyNumber = valueOf(profile, "policyNumber") ?? "Unknown";
-  const insuredName = valueOf(profile, "namedInsured") ?? "Unknown";
-  const carrier = valueOf(profile, "insurer") ?? "Unknown";
+  const namedInsuredParty = firstOperationalParty(profile, ["named_insured"]);
+  const insurerParty = firstOperationalParty(profile, ["insurer", "carrier"]);
+  const producerParty = firstOperationalParty(profile, ["producer", "broker"]);
+  const insuredName = valueOf(profile, "namedInsured") ?? namedInsuredParty?.name ?? "Unknown";
+  const carrier = valueOf(profile, "insurer") ?? insurerParty?.name ?? "Unknown";
   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 insurerProvenance = combinedProvenance(profile.insurer, insurerParty);
+  const insurerAddress = completeOperationalAddress(insurerParty?.address);
+  const broker = valueOf(profile, "broker") ?? producerParty?.name;
+  const brokerProvenance = combinedProvenance(profile.broker, producerParty);
+  const producerAddress = completeOperationalAddress(producerParty?.address);
   const mailingAddressFact = firstDeclarationFact(profile, "mailingAddress");
-  const insuredAddress = sourceBackedAddressFromFact(mailingAddressFact);
+  const insuredAddress = sourceBackedAddressFromParty(namedInsuredParty) ?? sourceBackedAddressFromFact(mailingAddressFact);
   const insuredDba = firstDeclarationFact(profile, "dba")?.value;
   const insuredEntityType = normalizedEntityType(firstDeclarationFact(profile, "entityType")?.value);
   const insuredFein = firstDeclarationFact(profile, "taxId")?.value;
@@ -5945,10 +6040,20 @@ function materializeDocument(params) {
     insuredEntityType,
     insuredFein,
     ...additionalNamedInsureds.length > 0 ? { additionalNamedInsureds } : {},
-    ...insurerProvenance ? { insurer: { legalName: carrier, ...insurerProvenance } } : {},
+    ...insurerProvenance ? {
+      insurer: {
+        legalName: carrier,
+        ...insurerAddress ? { address: insurerAddress } : {},
+        ...insurerProvenance
+      }
+    } : {},
     ...broker && brokerProvenance ? {
       brokerAgency: broker,
-      producer: { agencyName: broker, ...brokerProvenance }
+      producer: {
+        agencyName: broker,
+        ...producerAddress ? { address: producerAddress } : {},
+        ...brokerProvenance
+      }
     } : {},
     linesOfBusiness: profile.linesOfBusiness,
     formInventory: params.formInventory.filter((form) => typeof form.formNumber === "string" && form.formNumber.trim().length > 0).map((form) => ({