# FinOps-Agentic-Reconciliation

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

[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/)
[![SQL Engine](https://img.shields.io/badge/SQL-CTEs%20%26%20Window%20Functions-orange.svg)]()
[![MCP Server](https://img.shields.io/badge/MCP-Model%20Context%20Protocol-green.svg)]()
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

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

```mermaid
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
```bash
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
```bash
# 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
```bash
make test
```

### 4. Launch Ops Workbench Dashboard
```bash
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.