README.md

metadata

title: AP Agent Demo
emoji: 📄
colorFrom: blue
colorTo: purple
sdk: docker
app_file: app.py
pinned: false
license: mit

AP Agent Demo (Invoice ↔ PO Matching)

User-friendly web app for Accounts Payable processing:

• Upload Invoice document (PDF/DOCX/TXT) + PO CSV
• Auto checks: Invoice–PO match, back-order detection, duplicate invoice detection, supplier validation
• Persists history in local SQLite

Quickstart (FastAPI backend + React frontend)

This repo uses:

• Backend API: FastAPI (backend1/main.py)
• Frontend: React + Tailwind + Framer Motion (frontend/)

One-command (Windows) ⭐

If you're on Windows and want the easiest way to start everything:

.\run-dev.ps1

This script starts:

• the backend on the first free port from 8000, 8010, 8020, ...
• the frontend on http://localhost:5173 with the correct API proxy target

Backend

Set env vars:

• AZURE_OPENAI_ENDPOINT
• AZURE_OPENAI_API_KEY
• AZURE_OPENAI_DEPLOYMENT
• (optional) AZURE_OPENAI_API_VERSION

Optional (real OCR for scanned invoices):

• AZURE_DOCUMENT_INTELLIGENCE_ENDPOINT
• AZURE_DOCUMENT_INTELLIGENCE_KEY
• (optional) AZURE_DOCUMENT_INTELLIGENCE_API_VERSION

Troubleshooting (common):

• Make sure your frontend is talking to the backend1 server (health shows "service":"backend1"). Old servers on 8010 may respond with just {"ok":true}.
• If your backend is on port 8020, run frontend with: VITE_API_PROXY_TARGET=http://127.0.0.1:8020

Run:

python -m pip install -r requirements.txt
python -m uvicorn backend1.main:app --reload --port 8010

If you can't use port 8000 on your machine: it's usually because another app/service is already listening on it. In our environment we found a Windows service EZ Capture OCREngineV1 (NSSM) running uvicorn main:app --port 8000.

Frontend

In a new terminal:

cd frontend
npm install
npm run dev

Optional: point the frontend at a different API URL:

• set VITE_API_BASE_URL (defaults to http://127.0.0.1:8010 in dev; in production it uses relative /api/*)
• or set VITE_API_PROXY_TARGET (controls the Vite dev-server proxy for /api/*)

Note: If port 8010 is taken on your machine, use any free port (e.g. 8020) and set VITE_API_BASE_URL / VITE_API_PROXY_TARGET accordingly.

Single app (one server, one URL) ✅

For a single "real web app" (frontend + backend served together):

1. Build the frontend once:

cd frontend
npm install
npm run build
cd ..

2. Run the server:

python -m pip install -r requirements.txt
python -m uvicorn backend1.main:app --reload --port 8010

Open: http://localhost:8010

Hugging Face Spaces Deployment

This app can be deployed to Hugging Face Spaces using Docker.

Setup

1. Create a new Space on Hugging Face
2. Select "Docker" as the SDK
3. Push this repository to the Space
4. Set environment variables in Space settings:
   • AZURE_OPENAI_ENDPOINT
   • AZURE_OPENAI_API_KEY
   • AZURE_OPENAI_DEPLOYMENT
   • AZURE_OPENAI_API_VERSION (optional)

The Dockerfile will:

• Build the React frontend
• Install Python dependencies
• Serve the app on port 7860

AI Agent (recommended)

This demo supports an AI-powered agent mode for:

• Better invoice field/line-item extraction
• A model-driven final settlement decision (with rationale) using PO/history/supplier evidence

Enable

• UI: Expand "AI Agent settings", toggle it on, choose Azure OpenAI or OpenAI, then type YES to allow model calls.
• Env var (OpenAI): set OPENAI_API_KEY before running the app
• Env var (Azure OpenAI): set AZURE_OPENAI_ENDPOINT, AZURE_OPENAI_API_KEY (optional: AZURE_OPENAI_API_VERSION)

Local .env (optional)

Create a .env in the project root (optional) and fill in:

• AZURE_OPENAI_ENDPOINT
• AZURE_OPENAI_API_KEY
• AZURE_OPENAI_DEPLOYMENT

The app will fall back to rules-only mode if no API key is provided.

Feature rollout (only when you say YES)

This demo is structured so capabilities can be enabled incrementally.

Implemented now:

• Item 1: Detailed match insights (line-level mismatch reasons + optional AI explanation)
• Item 2: Backorder detection + monitoring (history-based remaining quantities + optional AI summary)

Data formats

PO CSV

Expected columns (case-insensitive; extra columns are OK):

• po_number (required)
• sku (recommended)
• description (required if sku missing)
• qty_ordered (required)
• unit_price (optional)

The AI agent can handle any column names dynamically - it will intelligently identify PO number, SKU, description, quantity, etc. from your CSV structure.

Invoice

Supported formats:

• PDF (text extraction + optional OCR)
• DOCX
• TXT

The AI agent extracts invoice fields and line items dynamically from any invoice format.