FlowMatch: Autonomous Accounts Payable Agent

A prototype architecture for automating financial 3-way matching (Purchase Order, Goods Receipt, and Invoice) using a hybrid approach of Agentic Data Extraction and Deterministic Financial Logic.

This project was designed to demonstrate architectural maturity in fintech AI by strictly separating probabilistic language models from deterministic mathematical validation.

The Hybrid Architecture

LLMs are exceptional at reading unstructured text and drafting emails, but they are notoriously unreliable at strict math and threshold logic. FlowMatch solves this by dividing the workflow into three distinct layers:

1. Extraction (Agentic / Probabilistic): Uses Gemini 2.5 Flash and google-genai to ingest unstructured vendor invoices and force the output into strict, predefined Pydantic JSON schemas.
2. Validation (Deterministic): Uses pure Python logic to compare line items, check tolerances, and validate quantities. No AI is used here, ensuring 100% auditability for the finance team.
3. Action (Agentic / Generative): If the deterministic check fails, the AI reads the specific discrepancies and drafts a context-aware, professional email to the vendor to resolve the mismatch.

Project Structure

flowmatch/
├── .env                # Environment variables (GEMINI_API_KEY)
├── requirements.txt    # Project dependencies
├── models.py           # Pydantic schemas (Data Layer)
├── engine.py           # Pure Python math/matching logic (Validation Layer)
├── agent.py            # Gemini 2.5 Flash API calls (AI Layer)
└── main.py             # Main orchestrator script

Quick Start

1. Clone the repository and set up a virtual environment:

   git clone https://github.com/YOUR_USERNAME/flowmatch.git
   cd flowmatch
   python -m venv venv
   source venv/bin/activate  # Or venv\Scripts\activate on Windows

2. Install dependencies:

   pip install -r requirements.txt

3. Configure the environment: Create a .env file in the root directory and add your Google Gemini API key:

   GEMINI_API_KEY=your_api_key_here

4. Run the agent:

   python main.py

Production Roadmap & Known Limitations

This repository serves as a conceptual prototype. A true enterprise-ready version would require the following implementations:

• Multimodal Document Processing: Currently, the invoice is mocked as unstructured text. In V2, the agent must handle raw, multi-page PDFs using Gemini's native vision capabilities or an OCR pipeline.
• State Management & Persistence: The script currently runs procedurally and exits. Production requires a database (e.g., PostgreSQL) to track workflow states (e.g., PENDING_VENDOR_REPLY, APPROVED) and manage state boundaries.
• Financial Edge Cases: Real-world 3-way matching must account for complex variables not present in this prototype, including partial shipments across multiple Goods Receipts, freight charges, distinct tax line items, and multi-currency conversions.
• ERP Integration: The agent needs API integrations to pull PO/GR data live from systems like NetSuite, Xero, or SAP, and push approved invoices back for payment clearing.
• Human-in-the-Loop (HITL) UI: An interface for AP clerks to manually review flagged edge cases before the AI fires off emails.