Route cash payment review through local agent with safe progress

app/modules/documents/local_agent_runtime/erp_local_agent/__init__.py

@@ -1,2 +1,2 @@
-__version__ = "1.22.5"
+__version__ = "1.22.6"
 AGENT_NAME = "ERP Local Agent"

app/modules/documents/local_agent_runtime/erp_local_agent/commands.py

@@ -1,7 +1,8 @@
 from __future__ import annotations
 
-from datetime import datetime, timezone
+from datetime import datetime, timezone, date as _dt_date, timedelta as _timedelta
 import re
+import time
 from typing import Any
 
 from . import __version__
@@ -661,7 +662,13 @@ class AgentCommandProcessor:
         if not 1 <= near_limit_percent <= 100:
             raise ValueError("Near-limit percentage must be between 1 and 100.")
 
+        # TallyPrime is intentionally queried in a paced manner. A full-year XML
+        # voucher export in one request can make desktop Tally unresponsive on
+        # larger books. Load masters once, pause briefly, then read vouchers in
+        # month-sized batches with a small gap between calls.
+        pace_seconds = 0.75
         ledger_masters = self.tally.export_master_collection(company_name, "ledgers")
+        time.sleep(pace_seconds)
         cash_ledgers = set()
         for ledger in ledger_masters:
             name = str(ledger.get("name") or "").strip()
@@ -672,7 +679,27 @@ class AgentCommandProcessor:
         if not cash_ledgers:
             cash_ledgers.add("cash")
 
-        vouchers = self.tally.export_vouchers(company_name, date_from, date_to)
+        try:
+            scan_from = _dt_date.fromisoformat(date_from)
+            scan_to = _dt_date.fromisoformat(date_to)
+        except ValueError as exc:
+            raise ValueError("Cash payment review dates must be valid YYYY-MM-DD dates.") from exc
+        if scan_to < scan_from:
+            raise ValueError("Cash payment review To date cannot be before From date.")
+
+        vouchers = []
+        batch_count = 0
+        cursor = scan_from
+        while cursor <= scan_to:
+            next_month = (cursor.replace(day=28) + _timedelta(days=4)).replace(day=1)
+            batch_to = min(scan_to, next_month - _timedelta(days=1))
+            batch = self.tally.export_vouchers(company_name, cursor.isoformat(), batch_to.isoformat())
+            vouchers.extend(batch or [])
+            batch_count += 1
+            cursor = batch_to + _timedelta(days=1)
+            if cursor <= scan_to:
+                time.sleep(pace_seconds)
+
         payments = []
         for voucher in vouchers:
             if str(voucher.get("is_cancelled") or "").strip().lower() in {"yes", "true", "1"}:
@@ -798,6 +825,9 @@ class AgentCommandProcessor:
                 "possible_split_payments": split_patterns,
                 "cash_payments": payments,
                 "read_only": True,
+                "safe_paced_mode": True,
+                "tally_request_batches": batch_count,
+                "tally_pause_ms": int(pace_seconds * 1000),
                 "review_note": "Possible split-payment patterns are review indicators only and do not determine tax treatment.",
             },
             "agent": self._agent_info(),