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** 🚀