README.md

metadata

title: Invoice OCR System
emoji: 📄
colorFrom: blue
colorTo: indigo
sdk: docker
pinned: false
license: mit
app_port: 7860

📄 Invoice OCR System

High-accuracy invoice processing powered by Google Document AI + Gemini 2.0 Flash

🔒 Access Control: Restricted to authorized users only via Hugging Face OAuth

🚀 Features

✅ Complete Invoice Extraction:

• Supplier information (name, address, tax ID)
• Customer/Bill-to information
• Invoice metadata (number, dates, PO, terms)
• Line items (code, description, type, qty, unit, price, total)
• Financial summary (subtotal, tax, total)
• Payment information

✅ Type Classification: Automatic categorization (produce, protein, beverage, dairy, grain, condiment, cleaning, packaging, miscellaneous)
✅ Validation & Correction: Mandatory math validation with ±2% tolerance
✅ Cost Tracking: Real-time processing cost calculation (~$0.002 per invoice)
✅ Image + Text Mode: Maximum accuracy with dual validation
✅ SQLite Database: Complete invoice history
✅ REST API: FastAPI backend with 7 endpoints
✅ Web Interface: Drag-and-drop upload with instant results
✅ Authentication: User whitelist for secure access

---

💰 Cost Per Invoice

Component	Cost
Document AI OCR	$0.001500
Gemini 2.0 Flash Input (~2,000 tokens)	$0.000200
Gemini 2.0 Flash Output (~800 tokens)	$0.000320
TOTAL	~$0.002

Free Tier: First 1,000 invoices/month FREE!

---

📋 Setup

1. Install Dependencies

pip install -r requirements.txt

2. Configure Environment

Create .env file:

PROJECT_ID=your_project_id
LOCATION=eu
PROCESSOR_ID=your_processor_id
GEMINI_API_KEY=your_gemini_key
GOOGLE_APPLICATION_CREDENTIALS=path_to_credentials.json

3. Run Server

python app.py

4. Open Browser

http://localhost:7860

---

🔧 API Endpoints

POST /upload          # Upload and process invoice
GET /invoices         # List all invoices
GET /invoices/{id}    # Get specific invoice
DELETE /invoices/{id} # Delete invoice
GET /stats            # Get statistics

---

📊 Invoice Data Structure

{
  "supplier": {
    "name": "Acme Corp",
    "address": "123 Business St",
    "tax_id": "12-3456789"
  },
  "customer": {
    "name": "Customer Inc",
    "address": "456 Client Ave"
  },
  "invoice_details": {
    "invoice_number": "INV-2025-001",
    "invoice_date": "2025-10-15",
    "due_date": "2025-11-15",
    "payment_terms": "Net 30"
  },
  "line_items": [
    {
      "item_code": "PROD-001",
      "description": "Widget Pro",
      "quantity": 10,
      "unit": "pcs",
      "unit_price": 100.00,
      "total_price": 1000.00
    }
  ],
  "financial_summary": {
    "subtotal": 1000.00,
    "tax_amount": 100.00,
    "total_amount": 1100.00,
    "currency": "USD"
  }
}

---

🚀 Deploy to Hugging Face Spaces (with Authentication)

1. Create Space

• Go to https://huggingface.co/new-space
• Name: invoice-ocr (or your choice)
• SDK: Docker
• Visibility: Private or Public (authentication works for both)
• Click "Create Space"

2. Clone and Add Files

git clone https://huggingface.co/spaces/YOUR_USERNAME/invoice-ocr
cd invoice-ocr

Copy all files to the cloned directory:

# Copy from your local development directory
cp Dockerfile requirements.txt app.py ocr_invoice.py cost_tracker.py auth.py allowed_users.txt ./
cp -r static/ ./

3. Configure User Whitelist

Option A: Using allowed_users.txt file (Recommended)

Edit allowed_users.txt and add authorized Hugging Face usernames (one per line):

johndoe
janedoe
companyuser1

Option B: Using Environment Variable

In Space settings → Variables & Secrets, add:

ALLOWED_USERS=johndoe,janedoe,companyuser1

4. Add Google Cloud Secrets

In Space settings → Variables & Secrets, add these as Secrets:

Name	Value	Example
PROJECT_ID	Your GCP project ID	836634225535
LOCATION	Document AI location	eu
PROCESSOR_ID	Document AI processor ID	696ca0c7b4383217
GEMINI_API_KEY	Your Gemini API key	AIza...
GOOGLE_APPLICATION_CREDENTIALS	Full JSON content from service account key	{"type":"service_account","project_id":"..."}

⚠️ Important: For GOOGLE_APPLICATION_CREDENTIALS, paste the entire JSON file content as the secret value, not the file path.

5. Deploy

git add .
git commit -m "Deploy invoice OCR with authentication"
git push

6. Enable Authentication (Critical Step)

After deployment, in your Space settings:

1. Go to Settings → General
2. Scroll to Sign-in with Hugging Face
3. Enable the toggle
4. Select Restricted (only whitelisted users can access)

This enables OAuth login before accessing your Space.

7. Test Access

1. Open your Space URL: https://huggingface.co/spaces/YOUR_USERNAME/invoice-ocr
2. You'll be prompted to sign in with Hugging Face
3. Only users in your whitelist can access the app
4. Unauthorized users see "Access Denied" page

---

🔒 Authentication Details

How It Works

1. Hugging Face OAuth: Users must sign in with their HF account
2. Whitelist Check: auth.py checks username against allowed list
3. Protected Endpoints: Upload, invoice retrieval, stats require authentication
4. Public Access: Only the login page and static files are public

Whitelist Format

allowed_users.txt (supports BOTH usernames AND emails):

# Hugging Face usernames (if you know them)
johndoe
janedoe

# OR email addresses (if you don't know usernames)
john@company.com
jane@company.com

# You can mix both!

Environment Variables:

# Option 1: Usernames
ALLOWED_USERS=johndoe,janedoe,companyuser1

# Option 2: Emails
ALLOWED_EMAILS=john@company.com,jane@company.com

# Or use both!

💡 Don't know the username? Just use their email address! The system checks both.

Protected Endpoints

✅ POST /upload - Upload invoice
✅ GET /invoices - List invoices
✅ GET /invoices/{id} - Get invoice details
✅ GET /invoices/{id}/debug - Debug data
✅ DELETE /invoices/{id} - Delete invoice
✅ GET /stats - Statistics

❌ GET / - Public (serves login page)
❌ GET /static/* - Public (CSS, JS, logo)

Local Development

Authentication is disabled when running locally (not in HF Space):

python app.py  # No auth required on localhost:7860

To test authentication locally, set:

export SPACE_ID=test
export ALLOWED_USERS=your_hf_username

---

📈 Performance

• Processing Time: 2-4 seconds per invoice
• Accuracy: 99%+ text extraction
• Cost: ~$0.002 per invoice
• Free Tier: 1,000 invoices/month FREE

---

🆚 vs Receipt OCR

Feature	Receipt OCR	Invoice OCR
Use Case	Retail receipts	B2B invoices
Line Items	Simple items	Item codes + details
Complexity	Low	Medium-High
Tokens	~2,000	~2,800
Cost	$0.001881	$0.002020
Fields	15-20	30-40

---

🛠️ Technology Stack

• OCR: Google Document AI OCR
• AI: Gemini 2.0 Flash (image + text)
• Backend: FastAPI + SQLAlchemy
• Database: SQLite
• Frontend: HTML5 + Vanilla JS
• Authentication: Hugging Face OAuth + Whitelist
• Deployment: Docker + Hugging Face Spaces

---

📝 License

MIT License

---

Built for accurate B2B invoice processing 🚀