Hugging Face's logo

Spaces:
chefcode
/
chefcodeocr
Sleeping

App Files Community
chefcodeocr / README.md
Mariem-Daha's picture
Mariem-Daha
Upload 22 files
8c33e8e verified
preview code
|
raw
history blame
8 kB
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 🚀