Spaces:
Sleeping
Sleeping
Download src/reconciliation_engine.py from MDBG-user/Doc_ShopPro_Portal: direct link, hf CLI and curl.
- Browser
- Download file 7.44 kB
-
https://huggingface.co/spaces/MDBG-user/Doc_ShopPro_Portal/resolve/main/src/reconciliation_engine.py
- Command line
-
hf download hf://spaces/MDBG-user/Doc_ShopPro_Portal/src/reconciliation_engine.py
-
curl -L -o reconciliation_engine.py https://huggingface.co/spaces/MDBG-user/Doc_ShopPro_Portal/resolve/main/src/reconciliation_engine.py
7.44 kB
| """ | |
| 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 | |