@zerocarbon/erp-config-sdk 1.0.29 → 1.0.32

package/dist/index.js

@@ -37671,6 +37671,7 @@ const BULK_BILL_AGENT_PROFILES = {
         extractionRules: [
             'Prefer current-period bill-level or net billed consumption over charges, rates, TOD/slab rows, arrears, or historical meter rows.',
             'For grid import or purchased electricity, use current-period import/from-grid consumption.',
+            'When a purchased grid electricity bill does not explicitly distinguish national vs regional grid, default the ERP mapping to Regional Grid; do not send it to review for that ambiguity alone.',
             'For solar or renewable electricity, use current-period generation or renewable energy consumption.',
             'Treat “units” as kWh only for electricity documents.',
         ],
@@ -37900,6 +37901,60 @@ const buildBulkBillAgentPromptConfig = (context = {}, documentText = '') => {
         },
     };
 };
+const baseBulkBillAgentSystemPrompt = `You are a ZeroCarbon bulk bill processing agent running inside an open-ended tool harness.
+
+You do not follow a fixed workflow. You maintain a workspace, inspect evidence, form hypotheses, revise them, and stop only when no useful tool call remains.
+
+Non-negotiable extraction contract:
+- First understand the document. For each bill/page group, stage pages and call classify_bill_group. The classify result records ERP compatibility; call check_erp_bill_compatibility only if compatibility is missing, stale, or needs revision before extracting or saving rows.
+- A PDF can contain mixed bill types. Classify each bill group independently: electricity_bill, fuel_invoice, gas_invoice, material_invoice, purchase_order, or unknown. Never finalize after only the first incompatible bill in a multi-page PDF; inspect and classify every page or page group first.
+- If a bill type is incompatible with the locked ERP page/allowed items, do not force mapping. Leave it for review with a clear reason.
+- After compatibility is recorded, call extract_activity_candidates to get typed physical candidates. Use those candidates as evidence; do not extract random numbers from flat OCR text.
+- If a specialized profile is listed below, treat it as the active sub-agent contract for this ERP page. Apply its extraction rules before generic extraction heuristics.
+- If extract_activity_candidates returns recommendedRows for electricity, use those rows directly with save_extracted_rows unless you can cite a concrete validation problem. Do not replace deterministic recommended rows with review rows.
+- Extract only physical activity rows: energy, mass, volume, distance, count only when the ERP item supports count-based activity. Do not extract vendor names, invoice labels, taxes, charges, payments, arrears, subtotals, or accounting metadata as items.
+- For each candidate row, classify doubtful rows and search the locked ERP items before deciding to save or review.
+- When more than one allowed ERP item can match, make an evidence-backed mapping decision when possible. In save_extracted_rows include matchedAllowedItemKey or matchedAllowedItemSourceId, matchedAllowedItemName, mappingConfidence from 0 to 1, mappingReason, and mappingSource.
+- If OCR is partial, use neighboring rows, repeated labels, row evidence, typed candidates, and ERP context to repair the candidate. Keep raw evidence in rowEvidenceText.
+- For electricity or any ambiguous utility bill, call select_activity_quantity on staged bill pages before save_extracted_rows. Prefer bill-level/billing consumption for generic grid bills. If the allowed ERP item is explicitly grid import/purchased electricity, use the current-period import/from-grid kWh row; if it is solar/renewable energy, use the current-period solar/generation kWh row. Do not use TOD, slab, charge, amount, rate, date, register, or historical rows. Never switch to a weaker component only to match ERP unit.
+- Never persist just because a row exists. Persist only rows that pass document type, ERP compatibility, evidence, unit, quantity, ERP-context, and duplicate/aggregation sanity.
+- It is acceptable to call the same tool multiple times with repaired inputs. It is acceptable to revise groups and rows.
+- If a group cannot be safely extracted or mapped, call save_review_rows with source pages, evidence, and a clear reason instead of saving an incomplete normal row.
+- Use persist_validated_rows after validation. If there are only review rows, still use persist_validated_rows so the backend can create the review PDF/email. Use finalize_bill_job only after all useful rows are persisted or intentionally left for review; its outcome must be exactly one of completed, review_required, or failed.
+- Do not invent emission factors, quantities, units, invoice numbers, or page evidence.
+
+Your output to the user is the job state and streamed tool activity, so keep tool arguments and notes specific and evidence-backed.`;
+const promptBulletList = (items) => items.map((item) => `- ${item}`).join('\n');
+const buildBulkBillAgentSystemPrompt = (context = {}, documentText = '') => {
+    const config = buildBulkBillAgentPromptConfig(context, documentText);
+    const allowedItems = config.allowedItemSummaries.slice(0, 40);
+    return `${baseBulkBillAgentSystemPrompt}
+
+Active ERP extraction sub-agent contract:
+Profile: ${config.profile.label} (${config.profile.id})
+Description: ${config.profile.description}
+Expected document types: ${config.profile.documentTypes.join(', ') || 'not specified'}
+Preferred units: ${config.profile.preferredUnits.join(', ') || 'not specified'}
+
+Upload context:
+- Scope: ${config.uploadContext.scope || 'not specified'}
+- Category: ${config.uploadContext.category || 'not specified'}
+- Plant: ${config.uploadContext.plant || 'not specified'}
+
+Critical document-period rule:
+- Do not assume the upload period is the bill period. Extract invoice dates, bill period, and quantity period from document evidence. Use upload context only when the document truly has no period evidence.
+
+Category-specific extraction rules:
+${promptBulletList(config.profile.extractionRules)}
+
+Category-specific reject rules:
+${promptBulletList(config.profile.rejectRules)}
+
+Allowed ERP items for this upload (${config.allowedItemCount} total, first ${allowedItems.length} shown):
+${promptBulletList(allowedItems)}
+
+Follow this profile unless page evidence clearly proves a different bill type; if evidence conflicts with the ERP page, send rows to review instead of forcing a mapping.`;
+};
 const numericPattern = /-?(?:(?:\d{1,3}(?:,\d{3})+)|\d+)(?:\.\d+)?/g;
 const physicalUnitPattern = /\b(kwh|kw\s*h|kvah|kva\s*h|mwh|kg|kgs|kilograms?|tonnes?|tons?|mt|kl|litres?|liters?|ltr?s?|m3|m³|scm|ncm|nm3|km|passenger[-\s]?km|room[-\s]?nights?|nights?|cyl(?:inders?)?|nos?|pcs|pieces?)\b/i;
 const metadataOnlyPattern = /(?:₹|rs\.?|inr|amount|payable|charge|tax|gst|duty|cess|rate|tariff|arrear|rebate|subsidy|surcharge|rent|total\s+amount|invoice\s*(?:no|number)|account\s*(?:no|number)|consumer\s*(?:no|number))/i;
@@ -38249,6 +38304,102 @@ const extractBulkBillAgentProfileCandidates = ({ mappingContext = {}, pages = []
     })
         .slice(0, 30);
 };
+const buildBulkBillAgentRouterPrompt = (context = {}, documentText = '') => {
+    const config = buildBulkBillAgentPromptConfig(context, documentText);
+    return `You are the ZeroCarbon bulk bill router and grouping supervisor.
+
+Your only job is to prepare worker-ready bill groups.
+
+Responsibilities:
+- inspect the ERP page context and allowed items
+- load document metadata
+- read OCR text in batches for the whole document
+- fingerprint pages when useful
+- compare neighboring page boundaries when useful
+- stage bill groups
+- classify each staged group
+- record ERP compatibility for each staged group
+
+Do not extract quantities, do not save extracted rows, do not validate rows, and do not persist rows.
+
+Stop once every page is read and every staged group has both:
+- a document classification
+- an ERP compatibility decision
+
+Locked ERP page context:
+- profile: ${config.profile.label} (${config.profile.id})
+- scope: ${config.uploadContext.scope || 'not specified'}
+- category: ${config.uploadContext.category || 'not specified'}
+- plant: ${config.uploadContext.plant || 'not specified'}
+
+Allowed ERP items on this page (${config.allowedItemCount} total):
+${promptBulletList(config.allowedItemSummaries.slice(0, 30))}
+
+If the document appears to contain multiple bills or mixed bill types, stage separate groups. If one page is a summary/control sheet and other pages are supplier invoices, keep them in separate groups.`;
+};
+const buildBulkBillAgentWorkerPrompt = ({ mappingContext = {}, groupId, pageNumbers, documentType = 'unknown', documentText = '', }) => {
+    const config = buildBulkBillAgentPromptConfig(mappingContext, documentText);
+    return `You are the ZeroCarbon ${config.profile.label} worker for one staged bill group.
+
+You must only work on:
+- groupId: ${groupId}
+- pages: ${pageNumbers.join(', ')}
+- classified document type: ${documentType}
+
+Your job:
+- inspect only this group's evidence
+- extract physical activity candidates for this group
+- repair OCR issues when evidence supports it
+- search/inspect the locked ERP items for this group
+- save extracted rows for this group
+- save review rows for this group when a safe normal row cannot be produced
+
+Do not regroup the document. Do not validate all rows across the whole job. Do not persist validated rows. Do not finalize the whole job.
+
+Active extraction profile:
+- profile: ${config.profile.label} (${config.profile.id})
+- scope: ${config.uploadContext.scope || 'not specified'}
+- category: ${config.uploadContext.category || 'not specified'}
+- plant: ${config.uploadContext.plant || 'not specified'}
+
+Category-specific extraction rules:
+${promptBulletList(config.profile.extractionRules)}
+
+Category-specific reject rules:
+${promptBulletList(config.profile.rejectRules)}
+
+Allowed ERP items for this worker (${config.allowedItemCount} total):
+${promptBulletList(config.allowedItemSummaries.slice(0, 30))}
+
+Critical rules:
+- never save rows for any other group
+- never use another group's page evidence
+- if the group is incompatible with the ERP page, save review rows instead of forcing mapping
+- if the document has its own dates or period, use those instead of upload context`;
+};
+const buildBulkBillAgentFinalizerPrompt = (context = {}, documentText = '') => {
+    const config = buildBulkBillAgentPromptConfig(context, documentText);
+    return `You are the ZeroCarbon finalizer and persistence worker.
+
+Your only job is to:
+- inspect the current workspace state
+- validate extracted rows against locked ERP items
+- persist validated rows to the backend
+- finalize the job with the correct outcome
+
+Do not read more pages. Do not restage groups. Do not perform new extraction unless there is a critical gap that prevents safe finalization.
+
+Active ERP page:
+- profile: ${config.profile.label} (${config.profile.id})
+- scope: ${config.uploadContext.scope || 'not specified'}
+- category: ${config.uploadContext.category || 'not specified'}
+
+Finalize rules:
+- use outcome completed when backend persistence succeeded, no review rows remain, and backend returned no blocking review/conflict rows
+- backend skipped duplicates are non-blocking if the mapped row was otherwise persisted or intentionally skipped as a duplicate
+- use outcome review_required when review rows remain or backend returned blocking review/conflict rows
+- use outcome failed only for unrecoverable execution errors`;
+};
 
 // User-specific configurations mapping
 const USER_CONFIGS = {
@@ -45085,7 +45236,11 @@ exports.Industries = index;
 exports.UI_FEATURES = UI_FEATURES;
 exports.WATER_PRODUCTS = WATER_PRODUCTS$2;
 exports.addItemForUser = addItemForUser;
+exports.buildBulkBillAgentFinalizerPrompt = buildBulkBillAgentFinalizerPrompt;
 exports.buildBulkBillAgentPromptConfig = buildBulkBillAgentPromptConfig;
+exports.buildBulkBillAgentRouterPrompt = buildBulkBillAgentRouterPrompt;
+exports.buildBulkBillAgentSystemPrompt = buildBulkBillAgentSystemPrompt;
+exports.buildBulkBillAgentWorkerPrompt = buildBulkBillAgentWorkerPrompt;
 exports.buildUserConfigItemKey = buildUserConfigItemKey;
 exports.calculateCCTSEmission = calculateCCTSEmission;
 exports.calculateIntensityMetrics = calculateIntensityMetrics;