algo-cli-runtime 0.14.0__py3-none-any.whl

algo_cli/intelligence/finance/ap_ar.py

@@ -0,0 +1,351 @@
+"""B91/B92/B93. AP duplicate, vendor SoD, and AR aging engines."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import date, datetime
+from decimal import Decimal
+from difflib import SequenceMatcher
+from typing import Any, Iterable
+
+from .common import ReviewGate, RiskLevel, SourceRef, decimalize, normalize_invoice_number, normalize_vendor_name, stable_exception_id, within_tolerance
+
+
+@dataclass(frozen=True)
+class APInvoice:
+    id: str
+    vendor: str
+    invoice_number: str
+    amount: Decimal | int | str
+    invoice_date: date | str
+    po_id: str | None = None
+    source_refs: list[SourceRef] = field(default_factory=list)
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "amount", decimalize(self.amount))
+        if isinstance(self.invoice_date, str):
+            object.__setattr__(self, "invoice_date", datetime.fromisoformat(self.invoice_date[:10]).date())
+
+
+@dataclass(frozen=True)
+class APPayment:
+    id: str
+    vendor: str
+    amount: Decimal | int | str
+    payment_date: date | str
+    invoice_number: str | None = None
+    source_refs: list[SourceRef] = field(default_factory=list)
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "amount", decimalize(self.amount))
+        if isinstance(self.payment_date, str):
+            object.__setattr__(self, "payment_date", datetime.fromisoformat(self.payment_date[:10]).date())
+
+
+@dataclass(frozen=True)
+class DuplicateCandidate:
+    invoice_ids: list[str]
+    payment_ids: list[str]
+    confidence: Decimal
+    reasons: list[str]
+    source_refs: list[SourceRef]
+    review_gate: ReviewGate = ReviewGate.CONTROLLER_REVIEW
+
+
+@dataclass(frozen=True)
+class ThreeWayMatchResult:
+    clean: bool
+    exceptions: list[str]
+    amount_difference: Decimal
+    quantity_difference: Decimal
+    tolerance_used: Decimal
+    review_gate: ReviewGate = ReviewGate.CONTROLLER_REVIEW
+
+
+class APDuplicateDetector:
+    """Find duplicate AP candidates and three-way match exceptions."""
+
+    def find_duplicates(
+        self,
+        invoices: Iterable[APInvoice | dict[str, Any]],
+        payments: Iterable[APPayment | dict[str, Any]] | None = None,
+        amount_tolerance: Decimal | int | str = Decimal("0"),
+        days_window: int = 7,
+    ) -> list[DuplicateCandidate]:
+        inv = [_coerce_invoice(row) for row in invoices]
+        pay = [_coerce_payment(row) for row in (payments or [])]
+        tolerance = decimalize(amount_tolerance)
+        candidates: list[DuplicateCandidate] = []
+        for i, left in enumerate(inv):
+            for right in inv[i + 1:]:
+                vendor_match = normalize_vendor_name(left.vendor) == normalize_vendor_name(right.vendor)
+                amount_match = within_tolerance(left.amount, right.amount, tolerance)
+                days = abs((left.invoice_date - right.invoice_date).days)
+                exact_invoice = normalize_invoice_number(left.invoice_number) == normalize_invoice_number(right.invoice_number)
+                near_invoice = _similar(left.invoice_number, right.invoice_number) >= Decimal("0.85")
+                if vendor_match and amount_match and (exact_invoice or (near_invoice and days <= days_window)):
+                    reasons = ["same vendor", "same amount"]
+                    confidence = Decimal("1.00") if exact_invoice else Decimal("0.75")
+                    reasons.append("same normalized invoice number" if exact_invoice else "near invoice number")
+                    candidates.append(DuplicateCandidate(
+                        invoice_ids=[left.id, right.id],
+                        payment_ids=[],
+                        confidence=confidence,
+                        reasons=reasons,
+                        source_refs=[*left.source_refs, *right.source_refs],
+                    ))
+        for payment in pay:
+            linked = [invoice for invoice in inv if normalize_vendor_name(invoice.vendor) == normalize_vendor_name(payment.vendor)
+                      and within_tolerance(invoice.amount, payment.amount, tolerance)
+                      and (not payment.invoice_number or normalize_invoice_number(invoice.invoice_number) == normalize_invoice_number(payment.invoice_number))]
+            if len(linked) > 1:
+                candidates.append(DuplicateCandidate(
+                    invoice_ids=[invoice.id for invoice in linked],
+                    payment_ids=[payment.id],
+                    confidence=Decimal("0.80"),
+                    reasons=["payment could apply to multiple matching invoices"],
+                    source_refs=[*payment.source_refs, *[ref for invoice in linked for ref in invoice.source_refs]],
+                ))
+        return sorted(candidates, key=lambda row: (row.confidence, row.invoice_ids), reverse=True)
+
+    def three_way_match(
+        self,
+        po: dict[str, Any],
+        receipt: dict[str, Any],
+        invoice: dict[str, Any],
+        price_tolerance: Decimal | int | str = Decimal("0.01"),
+        quantity_tolerance: Decimal | int | str = Decimal("0"),
+    ) -> ThreeWayMatchResult:
+        price_tol = decimalize(price_tolerance)
+        qty_tol = decimalize(quantity_tolerance)
+        po_qty = decimalize(po.get("quantity", 0))
+        receipt_qty = decimalize(receipt.get("quantity", 0))
+        invoice_qty = decimalize(invoice.get("quantity", 0))
+        po_price = decimalize(po.get("unit_price", 0))
+        invoice_price = decimalize(invoice.get("unit_price", 0))
+        exceptions: list[str] = []
+        if not within_tolerance(invoice_qty, receipt_qty, qty_tol):
+            exceptions.append("invoice quantity does not match receipt quantity")
+        if invoice_qty > po_qty + qty_tol:
+            exceptions.append("invoice quantity exceeds PO quantity")
+        if not within_tolerance(invoice_price, po_price, price_tol):
+            exceptions.append("invoice unit price does not match PO unit price")
+        po_amount = po_qty * po_price
+        invoice_amount = invoice_qty * invoice_price
+        amount_difference = invoice_amount - po_amount
+        quantity_difference = invoice_qty - receipt_qty
+        return ThreeWayMatchResult(
+            clean=not exceptions,
+            exceptions=exceptions,
+            amount_difference=amount_difference,
+            quantity_difference=quantity_difference,
+            tolerance_used=max(price_tol, qty_tol),
+        )
+
+
+@dataclass(frozen=True)
+class Vendor:
+    id: str
+    name: str
+    tax_id: str | None = None
+    bank_account: str | None = None
+    created_by: str | None = None
+    approved_by: str | None = None
+    active: bool = True
+    source_refs: list[SourceRef] = field(default_factory=list)
+
+
+@dataclass(frozen=True)
+class VendorChangeEvent:
+    id: str
+    vendor_id: str
+    field: str
+    changed_by: str
+    approved_by: str | None = None
+    changed_at: datetime | str | None = None
+    source_refs: list[SourceRef] = field(default_factory=list)
+
+    def __post_init__(self) -> None:
+        if isinstance(self.changed_at, str):
+            object.__setattr__(self, "changed_at", datetime.fromisoformat(self.changed_at))
+
+
+@dataclass(frozen=True)
+class VendorRisk:
+    vendor_id: str
+    score: Decimal
+    level: RiskLevel
+    reasons: list[str]
+    source_refs: list[SourceRef]
+
+
+@dataclass(frozen=True)
+class SoDConflict:
+    id: str
+    vendor_id: str
+    user: str
+    action: str
+    message: str
+    source_refs: list[SourceRef]
+
+
+class VendorRiskAnalyzer:
+    def score(
+        self,
+        vendors: Iterable[Vendor | dict[str, Any]],
+        changes: Iterable[VendorChangeEvent | dict[str, Any]] = (),
+        users: dict[str, Any] | None = None,
+    ) -> list[VendorRisk]:
+        vendor_rows = [_coerce_vendor(vendor) for vendor in vendors]
+        change_rows = [_coerce_change(change) for change in changes]
+        changes_by_vendor: dict[str, list[VendorChangeEvent]] = {}
+        for change in change_rows:
+            changes_by_vendor.setdefault(change.vendor_id, []).append(change)
+        risks: list[VendorRisk] = []
+        for vendor in vendor_rows:
+            score = Decimal("0")
+            reasons: list[str] = []
+            if not vendor.tax_id:
+                score += Decimal("150")
+                reasons.append("missing tax id")
+            if vendor.created_by and vendor.approved_by and vendor.created_by == vendor.approved_by:
+                score += Decimal("500")
+                reasons.append("creator approved vendor")
+            if not vendor.bank_account:
+                score += Decimal("100")
+                reasons.append("missing bank account")
+            sensitive_changes = [c for c in changes_by_vendor.get(vendor.id, []) if c.field.lower() in {"bank_account", "tax_id", "address"}]
+            if sensitive_changes:
+                score += Decimal("100") * len(sensitive_changes)
+                reasons.append("sensitive vendor master changes")
+            level = RiskLevel.CRITICAL if score >= 700 else RiskLevel.HIGH if score >= 400 else RiskLevel.MEDIUM if score >= 150 else RiskLevel.LOW
+            risks.append(VendorRisk(vendor_id=vendor.id, score=score, level=level, reasons=reasons, source_refs=list(vendor.source_refs)))
+        return sorted(risks, key=lambda row: (row.score, row.vendor_id), reverse=True)
+
+    def detect_sod_conflicts(self, events: Iterable[VendorChangeEvent | dict[str, Any]]) -> list[SoDConflict]:
+        conflicts: list[SoDConflict] = []
+        for event in [_coerce_change(e) for e in events]:
+            if event.approved_by and event.changed_by == event.approved_by:
+                conflicts.append(SoDConflict(
+                    id=stable_exception_id("B92", [event.vendor_id, event.id, event.changed_by]),
+                    vendor_id=event.vendor_id,
+                    user=event.changed_by,
+                    action=event.field,
+                    message=f"Same user changed and approved vendor {event.vendor_id}",
+                    source_refs=list(event.source_refs),
+                ))
+        return conflicts
+
+
+@dataclass(frozen=True)
+class ARInvoice:
+    id: str
+    customer: str
+    amount: Decimal | int | str
+    invoice_date: date | str
+    due_date: date | str
+    disputed: bool = False
+    customer_risk: RiskLevel = RiskLevel.MEDIUM
+    source_refs: list[SourceRef] = field(default_factory=list)
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "amount", decimalize(self.amount))
+        if isinstance(self.invoice_date, str):
+            object.__setattr__(self, "invoice_date", datetime.fromisoformat(self.invoice_date[:10]).date())
+        if isinstance(self.due_date, str):
+            object.__setattr__(self, "due_date", datetime.fromisoformat(self.due_date[:10]).date())
+
+
+@dataclass(frozen=True)
+class AgingBucket:
+    name: str
+    invoices: list[ARInvoice]
+    total: Decimal
+
+
+@dataclass(frozen=True)
+class AgingReport:
+    as_of: date
+    buckets: dict[str, AgingBucket]
+    total: Decimal
+
+
+@dataclass(frozen=True)
+class CollectionAction:
+    invoice_id: str
+    customer: str
+    priority_score: Decimal
+    reason: str
+    source_refs: list[SourceRef]
+
+
+class ARAgingPrioritizer:
+    def age(self, invoices: Iterable[ARInvoice | dict[str, Any]], as_of: date | str) -> AgingReport:
+        as_of_date = datetime.fromisoformat(as_of[:10]).date() if isinstance(as_of, str) else as_of
+        rows = [_coerce_ar_invoice(invoice) for invoice in invoices]
+        bucket_rows: dict[str, list[ARInvoice]] = {"current": [], "1-30": [], "31-60": [], "61-90": [], "90+": []}
+        for invoice in rows:
+            days = (as_of_date - invoice.due_date).days
+            bucket = "current" if days <= 0 else "1-30" if days <= 30 else "31-60" if days <= 60 else "61-90" if days <= 90 else "90+"
+            bucket_rows[bucket].append(invoice)
+        buckets = {
+            name: AgingBucket(name=name, invoices=values, total=sum((invoice.amount for invoice in values), Decimal("0")))
+            for name, values in bucket_rows.items()
+        }
+        return AgingReport(as_of=as_of_date, buckets=buckets, total=sum((invoice.amount for invoice in rows), Decimal("0")))
+
+    def prioritize_collections(self, invoices: Iterable[ARInvoice | dict[str, Any]], payments=None, as_of: date | str | None = None) -> list[CollectionAction]:
+        as_of_date = datetime.fromisoformat(as_of[:10]).date() if isinstance(as_of, str) else as_of or date.today()
+        actions: list[CollectionAction] = []
+        for invoice in [_coerce_ar_invoice(row) for row in invoices]:
+            days_past_due = max((as_of_date - invoice.due_date).days, 0)
+            score = abs(invoice.amount) + Decimal(days_past_due) * Decimal("25") + Decimal(int(invoice.customer_risk)) * Decimal("200")
+            reasons = [f"{days_past_due} days past due", f"{invoice.customer_risk.name.lower()} customer risk"]
+            if invoice.disputed:
+                score += Decimal("500")
+                reasons.append("disputed")
+            actions.append(CollectionAction(
+                invoice_id=invoice.id,
+                customer=invoice.customer,
+                priority_score=score,
+                reason="; ".join(reasons),
+                source_refs=list(invoice.source_refs),
+            ))
+        return sorted(actions, key=lambda row: (row.priority_score, row.invoice_id), reverse=True)
+
+
+def _coerce_invoice(row: APInvoice | dict[str, Any]) -> APInvoice:
+    if isinstance(row, APInvoice):
+        return row
+    return APInvoice(str(row["id"]), str(row.get("vendor", "")), str(row.get("invoice_number", "")), row.get("amount", 0), row.get("invoice_date") or row.get("date"), row.get("po_id"), list(row.get("source_refs", [])))
+
+
+def _coerce_payment(row: APPayment | dict[str, Any]) -> APPayment:
+    if isinstance(row, APPayment):
+        return row
+    return APPayment(str(row["id"]), str(row.get("vendor", "")), row.get("amount", 0), row.get("payment_date") or row.get("date"), row.get("invoice_number"), list(row.get("source_refs", [])))
+
+
+def _similar(left: str, right: str) -> Decimal:
+    return decimalize(str(SequenceMatcher(None, normalize_invoice_number(left), normalize_invoice_number(right)).ratio()))
+
+
+def _coerce_vendor(row: Vendor | dict[str, Any]) -> Vendor:
+    if isinstance(row, Vendor):
+        return row
+    return Vendor(str(row["id"]), str(row.get("name", "")), row.get("tax_id"), row.get("bank_account"), row.get("created_by"), row.get("approved_by"), bool(row.get("active", True)), list(row.get("source_refs", [])))
+
+
+def _coerce_change(row: VendorChangeEvent | dict[str, Any]) -> VendorChangeEvent:
+    if isinstance(row, VendorChangeEvent):
+        return row
+    return VendorChangeEvent(str(row["id"]), str(row.get("vendor_id", "")), str(row.get("field", "")), str(row.get("changed_by", "")), row.get("approved_by"), row.get("changed_at"), list(row.get("source_refs", [])))
+
+
+def _coerce_ar_invoice(row: ARInvoice | dict[str, Any]) -> ARInvoice:
+    if isinstance(row, ARInvoice):
+        return row
+    risk = row.get("customer_risk", RiskLevel.MEDIUM)
+    if isinstance(risk, str):
+        risk = RiskLevel[risk.upper()]
+    return ARInvoice(str(row["id"]), str(row.get("customer", "")), row.get("amount", 0), row.get("invoice_date") or row.get("date"), row.get("due_date"), bool(row.get("disputed", False)), risk, list(row.get("source_refs", [])))

algo_cli/intelligence/finance/cash.py

@@ -0,0 +1,162 @@
+"""B94. 13-Week Cash Flow Forecast Engine."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import date, datetime, timedelta
+from decimal import Decimal
+from typing import Any, Iterable
+
+from .common import ReviewGate, SourceRef, decimalize, stable_exception_id
+
+
+@dataclass(frozen=True)
+class CashFlowItem:
+    id: str
+    amount: Decimal | int | str
+    due_date: date | str
+    category: str
+    description: str = ""
+    source_refs: list[SourceRef] = field(default_factory=list)
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "amount", decimalize(self.amount))
+        if isinstance(self.due_date, str):
+            object.__setattr__(self, "due_date", datetime.fromisoformat(self.due_date[:10]).date())
+
+
+@dataclass(frozen=True)
+class CashForecastWeek:
+    week_number: int
+    week_start: date
+    beginning_cash: Decimal
+    receipts: Decimal
+    disbursements: Decimal
+    ending_cash: Decimal
+    source_refs: list[SourceRef] = field(default_factory=list)
+
+
+@dataclass(frozen=True)
+class CashForecast:
+    starting_cash: Decimal
+    weeks: list[CashForecastWeek]
+    review_gate: ReviewGate = ReviewGate.CONTROLLER_REVIEW
+
+    @property
+    def ending_cash(self) -> Decimal:
+        return self.weeks[-1].ending_cash if self.weeks else self.starting_cash
+
+
+@dataclass(frozen=True)
+class ForecastVariance:
+    week_number: int
+    forecast_receipts: Decimal
+    actual_receipts: Decimal
+    forecast_disbursements: Decimal
+    actual_disbursements: Decimal
+    net_difference: Decimal
+    explanation: str
+    source_refs: list[SourceRef] = field(default_factory=list)
+
+
+@dataclass(frozen=True)
+class ForecastVarianceReport:
+    variances: list[ForecastVariance]
+    total_net_difference: Decimal
+
+
+class ThirteenWeekCashForecast:
+    """Weekly cash bridge: beginning cash + receipts - disbursements."""
+
+    def forecast(
+        self,
+        open_ar: Iterable[CashFlowItem | dict[str, Any]],
+        open_ap: Iterable[CashFlowItem | dict[str, Any]],
+        payroll: Iterable[CashFlowItem | dict[str, Any]],
+        recurring: Iterable[CashFlowItem | dict[str, Any]],
+        starting_cash: Decimal | int | str,
+        start_date: date | str | None = None,
+    ) -> CashForecast:
+        start = _coerce_date(start_date) if start_date else date.today()
+        start = start - timedelta(days=start.weekday())
+        receipts = [_coerce_item(item, "ar") for item in open_ar]
+        disbursements = [_coerce_item(item, "ap") for item in list(open_ap) + list(payroll) + list(recurring)]
+        beginning = decimalize(starting_cash)
+        weeks: list[CashForecastWeek] = []
+        for idx in range(13):
+            week_start = start + timedelta(days=idx * 7)
+            week_end = week_start + timedelta(days=6)
+            week_receipts = [item for item in receipts if week_start <= item.due_date <= week_end]
+            week_disb = [item for item in disbursements if week_start <= item.due_date <= week_end]
+            receipt_total = sum((abs(item.amount) for item in week_receipts), Decimal("0"))
+            disb_total = sum((abs(item.amount) for item in week_disb), Decimal("0"))
+            ending = beginning + receipt_total - disb_total
+            weeks.append(CashForecastWeek(
+                week_number=idx + 1,
+                week_start=week_start,
+                beginning_cash=beginning,
+                receipts=receipt_total,
+                disbursements=disb_total,
+                ending_cash=ending,
+                source_refs=[ref for item in [*week_receipts, *week_disb] for ref in item.source_refs],
+            ))
+            beginning = ending
+        return CashForecast(starting_cash=decimalize(starting_cash), weeks=weeks)
+
+    def variance(self, actuals: Iterable[dict[str, Any]], forecast: CashForecast) -> ForecastVarianceReport:
+        by_week = {week.week_number: week for week in forecast.weeks}
+        actual_by_week: dict[int, dict[str, Any]] = {}
+        for actual in actuals:
+            week = int(actual.get("week_number", 0))
+            actual_by_week[week] = actual
+        variances: list[ForecastVariance] = []
+        for week_number, week in by_week.items():
+            actual = actual_by_week.get(week_number, {})
+            actual_receipts = decimalize(actual.get("receipts", 0))
+            actual_disb = decimalize(actual.get("disbursements", 0))
+            if actual_receipts == 0 and actual_disb == 0 and week.receipts == 0 and week.disbursements == 0:
+                continue
+            net_diff = (actual_receipts - actual_disb) - (week.receipts - week.disbursements)
+            if net_diff == 0:
+                continue
+            explanation = _variance_explanation(week.receipts, actual_receipts, week.disbursements, actual_disb)
+            variances.append(ForecastVariance(
+                week_number=week_number,
+                forecast_receipts=week.receipts,
+                actual_receipts=actual_receipts,
+                forecast_disbursements=week.disbursements,
+                actual_disbursements=actual_disb,
+                net_difference=net_diff,
+                explanation=explanation,
+                source_refs=list(actual.get("source_refs", [])),
+            ))
+        total = sum((variance.net_difference for variance in variances), Decimal("0"))
+        return ForecastVarianceReport(variances=variances, total_net_difference=total)
+
+
+def _coerce_item(item: CashFlowItem | dict[str, Any], default_category: str) -> CashFlowItem:
+    if isinstance(item, CashFlowItem):
+        return item
+    return CashFlowItem(
+        id=str(item.get("id") or stable_exception_id("B94", [item.get("amount"), item.get("due_date"), item.get("description")])) ,
+        amount=item.get("amount", 0),
+        due_date=item.get("due_date") or item.get("date"),
+        category=str(item.get("category", default_category)),
+        description=str(item.get("description", "")),
+        source_refs=list(item.get("source_refs", [])),
+    )
+
+
+def _coerce_date(value: date | str) -> date:
+    return datetime.fromisoformat(value[:10]).date() if isinstance(value, str) else value
+
+
+def _variance_explanation(f_receipts: Decimal, a_receipts: Decimal, f_disb: Decimal, a_disb: Decimal) -> str:
+    receipt_diff = a_receipts - f_receipts
+    disb_diff = a_disb - f_disb
+    parts: list[str] = []
+    if receipt_diff:
+        parts.append("receipt timing/amount variance")
+    if disb_diff:
+        parts.append("disbursement timing/amount variance")
+    return "; ".join(parts) if parts else "no variance"