README.md

---
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
```bash
pip install -r requirements.txt
```

### 2. Configure Environment
Create `.env` file:
```bash
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
```bash
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

```json
{
  "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
```bash
git clone https://huggingface.co/spaces/YOUR_USERNAME/invoice-ocr
cd invoice-ocr
```

Copy all files to the cloned directory:
```bash
# 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
```bash
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):
```bash
python app.py  # No auth required on localhost:7860
```

To test authentication locally, set:
```bash
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** 🚀