Spaces:
Sleeping
Sleeping
File size: 7,442 Bytes
e1267ce | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 | """
reconciliation_engine.py
Reconciliation engine that uses exact-only matching.
It:
- Converts canonical DataFrames into InvoiceRecord / PaymentRecord objects
- Uses FuzzyMatcher (configured as exact-only) to find payment suggestions
- Builds ReconciliationMatch objects and wraps them in a ReconciliationResult
- Supports admin corrections and exporting to Excel/CSV
This matches the interface expected by app.py:
engine = ReconciliationEngine()
result = engine.reconcile(open_invoices_df, payment_notifications_df)
engine.apply_correction(record_id, correction)
engine.get_results()
engine.export_to_excel()
engine.export_to_csv()
"""
from __future__ import annotations
from typing import List, Tuple, Optional
from datetime import datetime
import os
import uuid
import tempfile
import pandas as pd
from .data_models import (
InvoiceRecord,
PaymentRecord,
ReconciliationMatch,
MatchStatus,
ReconciliationResult,
AdminCorrection,
)
from .matching_algorithms import MatchScorer, FuzzyMatcher
class ReconciliationEngine:
"""
High-level reconciliation engine.
- Uses exact-only matching (via FuzzyMatcher/MatchScorer).
- Produces ReconciliationResult compatible with the UI in app.py.
"""
def __init__(self) -> None:
self._results: ReconciliationResult = ReconciliationResult(matches=[])
# ------------------------------------------------------------------
# Public API used by app.py
# ------------------------------------------------------------------
def reconcile(
self,
open_invoices_df: pd.DataFrame,
payment_notifications_df: pd.DataFrame,
) -> ReconciliationResult:
"""
Run reconciliation given the canonical DataFrames and return ReconciliationResult.
"""
invoices = self._df_to_invoices(open_invoices_df)
payments = self._df_to_payments(payment_notifications_df)
scorer = MatchScorer()
matcher = FuzzyMatcher(scorer=scorer, threshold=1.0)
matches: List[ReconciliationMatch] = []
# For each invoice, find exact payment suggestions
for inv in invoices:
suggestions = matcher.get_suggestions(inv, payments)
if suggestions:
# We treat the first exact suggestion as the main match
best_payment, score = suggestions[0]
match_status = MatchStatus.EXACT_MATCH
linked_payment_id = best_payment.id
applied_payment_amount = best_payment.payment_amount
final_ar_status = "Paid"
confidence_score = score
else:
match_status = MatchStatus.UNMATCHED
linked_payment_id = None
applied_payment_amount = None
final_ar_status = inv.ar_status or "Unpaid"
confidence_score = 0.0
suggestions = [] # no payment suggestions
match = ReconciliationMatch(
record_id=inv.id,
invoice_record=inv,
match_status=match_status,
linked_payment_id=linked_payment_id,
payment_suggestions=suggestions,
applied_payment_amount=applied_payment_amount,
final_ar_status=final_ar_status,
admin_notes=None,
confidence_score=confidence_score,
is_approved=False,
approved_by=None,
approved_at=None,
)
matches.append(match)
self._results = ReconciliationResult(matches=matches)
return self._results
def apply_correction(self, record_id: str, correction: AdminCorrection) -> bool:
"""
Apply an admin correction to a specific ReconciliationMatch by record_id.
- Updates linked_payment_id, payment_amount, ar_status, notes.
- If action == 'approve', sets match_status=APPROVED and is_approved=True.
- If action == 'discrepancy', sets match_status=DISCREPANCY.
"""
if not self._results or not self._results.matches:
return False
target: Optional[ReconciliationMatch] = None
for m in self._results.matches:
if m.record_id == record_id:
target = m
break
if target is None:
return False
# Apply corrections
if correction.linked_payment_id is not None:
target.linked_payment_id = correction.linked_payment_id
if correction.payment_amount is not None:
target.applied_payment_amount = correction.payment_amount
if correction.ar_status is not None:
target.final_ar_status = correction.ar_status
if correction.admin_notes is not None:
target.admin_notes = correction.admin_notes
# Handle action
action = (correction.action or "").lower()
now = datetime.utcnow()
if action == "approve":
target.is_approved = True
target.match_status = MatchStatus.APPROVED
target.approved_at = now
# approved_by can be set later if you have user context
elif action == "discrepancy":
target.match_status = MatchStatus.DISCREPANCY
return True
def get_results(self) -> ReconciliationResult:
"""Return the current reconciliation results."""
return self._results
def export_to_excel(self) -> str:
"""
Export current reconciliation results to an Excel file and return the file path.
Used by app.export_results().
"""
df = self._results.to_dataframe()
if df.empty:
raise ValueError("No data to export")
tmp_dir = tempfile.gettempdir()
file_path = os.path.join(
tmp_dir,
f"reconciliation_results_{uuid.uuid4().hex}.xlsx",
)
df.to_excel(file_path, index=False)
return file_path
def export_to_csv(self) -> str:
"""
Export current reconciliation results to a CSV file and return the file path.
"""
df = self._results.to_dataframe()
if df.empty:
raise ValueError("No data to export")
tmp_dir = tempfile.gettempdir()
file_path = os.path.join(
tmp_dir,
f"reconciliation_results_{uuid.uuid4().hex}.csv",
)
df.to_csv(file_path, index=False)
return file_path
# ------------------------------------------------------------------
# Internal helpers
# ------------------------------------------------------------------
def _df_to_invoices(self, df: pd.DataFrame) -> List[InvoiceRecord]:
"""Convert canonical invoice DataFrame to list of InvoiceRecord objects."""
if df is None or df.empty:
return []
records: List[InvoiceRecord] = []
for row in df.to_dict(orient="records"):
records.append(InvoiceRecord(**row))
return records
def _df_to_payments(self, df: pd.DataFrame) -> List[PaymentRecord]:
"""Convert canonical payment DataFrame to list of PaymentRecord objects."""
if df is None or df.empty:
return []
records: List[PaymentRecord] = []
for row in df.to_dict(orient="records"):
records.append(PaymentRecord(**row))
return records
|