FinOps-Agentic-Reconciliation

Autonomous Procure-to-Pay (P2P) 3-Way Matching Data Pipeline, FastMCP Server, and Ops AI Resolution Engine

An enterprise-grade Finance Operations platform built to automate 3-way invoice reconciliation (PO vs. GRN vs. Invoice), audit line-item price & quantity variances, calculate financial exposure risk, and orchestrate autonomous discrepancy resolution using Model Context Protocol (MCP) tools.

---

📐 System Architecture

flowchart TD
    subgraph Data Layer [ERP Data Ingestion]
        PO[Purchase Orders CSV] --> DB[(SQLite / Postgres DB)]
        GRN[Goods Received Notes CSV] --> DB
        INV[Vendor Invoices CSV] --> DB
    end

    subgraph SQL Engine [Analytics & Reconciliation Pipeline]
        DB --> CTE[3-Way Matching SQL CTEs & Window Functions]
        CTE --> DISC[Discrepancy Matrix & Risk Scoring]
        DISC --> DB_TABLES[Populate Discrepancies & Audit Logs]
    end

    subgraph Agentic Layer [Model Context Protocol & Ops AI Agent]
        DB_TABLES <--> MCP[FastMCP Server]
        MCP <--> AGENT[Ops AI Agent Resolution Engine]
        AGENT --> POLICY[Corporate Financial Policy Rules]
        POLICY --> ACTIONS[Auto-Approve / Hold / Credit Note Request]
    end

    subgraph Executive Layer [UI & Observability]
        DB_TABLES --> DASHBOARD[Streamlit Executive & Ops Workbench]
        ACTIONS --> DASHBOARD
    end

---

🔥 Key Capabilities

1. Automated Procure-to-Pay (P2P) 3-Way Matching:

   • Executes line-item reconciliation across Purchase Orders, Goods Received Notes, and Vendor Invoices.
   • Categorizes financial anomalies: UNIT_PRICE_VARIANCE, QTY_SHORTAGE, MISSING_GRN, DUPLICATE_INVOICE.

2. Model Context Protocol (MCP) Server (src/mcp_server/):

   • Implements standard MCP JSON-RPC tool endpoints:
     • get_unmatched_invoices(status, min_severity)
     • run_3way_matching_audit(invoice_number)
     • trigger_vendor_hold(invoice_number, reason)
     • fetch_vendor_aging_summary(vendor_id)

3. Autonomous Ops AI Agent (src/agent/):

   • Processes flagged discrepancies in batches.
   • Evaluates corporate financial policies (e.g. 1% price variance tolerance, auto-hold on missing GRN, credit note request for overbilling).
   • Updates database state atomically and logs immutable audit trails.

4. Executive Ops Workbench & Analytics Dashboard (src/dashboard/app.py):

   • Dark-mode Streamlit dashboard with real-time KPI metrics (Auto-Match %, Financial Exposure Risk INR, Hours Saved).
   • Side-by-side PO vs. GRN vs. Invoice line-item comparison tool.
   • Live AI Agent execution terminal with simulation logs.
   • Accounts Payable aging buckets (Current, 1-30, 31-60, 60+ days) and vendor risk scatter matrix.

---

📊 Discrepancy Taxonomy & Policy Matrix

Anomaly Type	Condition	Severity	Financial Exposure	Autonomous Action
Immaterial Variance	Price variance $\le 1.0%$	LOW	Minor	AUTO_APPROVE
Unit Price Mismatch	Invoice rate > Agreed PO rate	HIGH / CRITICAL	(Billed Price - PO Price) * Qty	REQUEST_CREDIT_NOTE & ON_HOLD
Quantity Shortage	Billed Qty > GRN Received Qty	HIGH	Shortage Qty * Billed Price	APPROVE_PARTIAL & ON_HOLD
Missing GRN	Invoice received before warehouse receipt	HIGH	Total Billed Amount	HOLD_PAYMENT
Duplicate Invoice	Same PO/Invoice submitted multiple times	CRITICAL	Total Billed Amount	BLOCK_IMMEDIATELY

---

⚡ Quickstart Guide

1. Prerequisites & Environment Setup

git clone https://github.com/your-username/FinOps-Agentic-Reconciliation.git
cd FinOps-Agentic-Reconciliation

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

2. Generate ERP Data & Run Reconciliation Pipeline

# Generate 1,000+ realistic transaction records and run ETL pipeline
make etl

# Or run directly via Python:
python -m src.pipeline.etl_reconciliation

3. Run Automated Tests

make test

4. Launch Ops Workbench Dashboard

make dashboard

Open your browser at http://localhost:8501.

---

📁 Repository Structure

FinOps-Agentic-Reconciliation/
├── README.md                      # Technical documentation & architecture
├── pyproject.toml                 # Package configuration
├── requirements.txt               # Pinned dependencies
├── Makefile                       # Developer CLI shortcuts
├── config/
│   └── settings.yaml              # Financial thresholds & tolerance settings
├── data/
│   ├── raw_pos.csv                # Sample PO transactions
│   ├── raw_grns.csv               # Sample GRN receipts
│   └── raw_invoices.csv           # Sample Vendor Invoices
├── sql/
│   ├── 01_schema_init.sql         # Relational DDL & performance indexes
│   ├── 02_three_way_matching.sql  # 3-Way matching CTEs & window functions
│   └── 03_vendor_aging_kpis.sql   # AP aging aggregation queries
├── src/
│   ├── pipeline/
│   │   ├── generate_synthetic_data.py # ERP synthetic transaction generator
│   │   └── etl_reconciliation.py  # Main ETL reconciliation engine
│   ├── mcp_server/
│   │   └── ops_mcp_server.py      # FastMCP JSON-RPC server implementation
│   ├── agent/
│   │   ├── ops_agent.py           # FinOps AI Agent batch execution engine
│   │   └── discrepancy_rules.py   # Deterministic financial policies
│   └── dashboard/
│       └── app.py                 # Streamlit Executive Ops Workbench
└── tests/
    ├── test_reconciliation.py     # Discrepancy rule unit tests
    └── test_mcp_server.py         # MCP tool integration tests

---

🛡️ License

Distributed under the MIT License. See LICENSE for more information.