""" 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