Invoice Processing System

A Streamlit-based web application for processing and validating invoices using Vision Language Models (VLM). The application automatically extracts information from invoices and validates them against configurable business rules.

Features

• Upload and process invoices (PDF, PNG, JPG, JPEG)
• Automatic text and field extraction using VLM
• Configurable validation rules:
  • Company validation (Rihal - based on VATIN)
  • Amount threshold validation
  • Date range validation
• Interactive UI with adjustable parameters
• Options to overwrite flags or notify vendors
• Structured display of invoice details and line items

Project Structure

.
├── app/
│   ├── main.py        # Main Streamlit application
│   └── config.py      # Business rules and configuration
├── requirements.txt   # Project dependencies
├── .env              # API configuration (not in repo)
├── .env.template     # Template for .env file
└── Dockerfile        # Container configuration

Setup

1. Create and activate a virtual environment:

   # Create virtual environment
   python3 -m venv venv
   
   # Activate on Linux/Mac
   source venv/bin/activate
   
   # Activate on Windows
   .\venv\Scripts\activate
   

2. Install dependencies using uv:

   # Install uv first
   pip install uv
   
   # Install project dependencies
   uv pip install -r requirements.txt
   

3. Configure the environment:

   • Copy .env.template to .env
   • Update the VLM API endpoint in .env:

     VLM_API_ENDPOINT=http://your-vlm-endpoint:port/process
     

4. Run the application:

   streamlit run app/main.py
   

Configuration

Environment Variables (.env)

• VLM_API_ENDPOINT: URL of your VLM API endpoint

Business Rules (app/config.py)

• COMPANY_NAME: Company name to validate against (default: "Rihal")
• MAX_invoice_amount: Maximum allowed invoice amount (default: 50000.0)
• VALID_DATE_RANGE: Valid date range for invoices
  • "start": "2024-01-01"
  • "end": "2024-12-31"

VLM API Requirements

The VLM API should return a JSON response in the following format:

{
    "Customer Name": "C0000031 - Customer Name",
    "Customer Address": null,
    "Contact Person": null,
    "Contact VATIN": null,
    "Contact Person Tel": null,
    "Invoice Due Date": "15/05/2025",
    "Invoice Number": "RHL2025INV000053",
    "Document Date": "31/03/2025",
    "Reference Number": "PO# 26183",
    "PO Number": "26183",
    "currency": "OMR",
    "VATIN": "OM110001944X",
    "Invoice Date": "31/03/2025",
    "Date of Supply": "31/03/2025",
    "GL Code": "1200001",
    "Item Details": [
        {
            "Description": "Item Description",
            "UOM": "Unit",
            "QTY": "1.00",
            "Sales Price %": "0.00",
            "Discount %": "0.00",
            "Selling Unit Price": "100.000",
            "Taxable Amount": "100.000",
            "VAT": "5%",
            "VAT Amount": "5.000",
            "Net Amount (OMR)": "105.000"
        }
    ],
    "Sub Total (Excluding VAT)": "100.000",
    "Total VAT (OMR) (5%)": "5.000",
    "Total Amount Payable": "105.000",
    "Total Amount Payable in Word": null
}

Important Fields

• VATIN: Used to validate if invoice is from Rihal (must be "OM110001944X")
• Invoice Date: Used for date validation (format: DD/MM/YYYY)
• Total Amount Payable: Used for amount validation
• Item Details: Displayed in a structured table format

Docker Support

1. Build the image:

   docker build -t invoice-processor .
   

2. Run the container:

   docker run -p 8501:8501 -v $(pwd)/.env:/app/.env invoice-processor
   

Access the application at http://localhost:8501

Development

• The application uses Streamlit for the web interface
• Business rules are configured in app/config.py
• VLM integration is handled through environment variables
• All validation rules can be adjusted through the UI
• The sidebar provides real-time parameter adjustment

Notes

• Keep your .env file secure and never commit it to version control
• The VLM API should be properly secured and accessible
• All monetary values are handled as floats with 2 decimal places
• Date validation uses the datetime format YYYY-MM-DD internally
• The application expects dates in DD/MM/YYYY format from the API
• VATIN validation is used to identify Rihal invoices