OCR Invoice Processing System

Automated end-to-end invoice processing pipeline: OCR extraction → Intelligent mapping → CRM integration → Quality reporting

---

Features

Component	Technology	Purpose
OCR Engine	Ollama minicpm-v	Extract text from invoice images
Smart Mapper	Llama 3.2 LLM	Convert text to structured JSON with auto-repair
CRM Integration	Odoo XML-RPC	Automatically sync invoices to CRM
Quality Reports	PostgreSQL + FPDF2	Generate confidence scores & PDF reports
Auto-Archive	File management	Organize processed invoices

---

Installation

Prerequisites

• Python 3.8+
• Ollama running locally
• PostgreSQL (for quality reports)
• Odoo CRM (optional, for sync feature)

Setup

# 1. Clone repository
git clone <your-repo-url>
cd ocr-system

# 2. Install dependencies
pip install -r requirements.txt

# 3. Pull required Ollama models
ollama pull minicpm-v      # Vision OCR model
ollama pull llama3.2       # Intelligent mapping model

# 4. Start PostgreSQL (for reports)
# On macOS with Homebrew:
brew services start postgresql

# 5. Configure settings (optional)
# Edit config/settings.py for custom paths, CRM credentials, etc.

---

🎯 Quick Start

Basic Usage

# Process all invoices in data/input/
python3 main.py

# Process specific invoice
python3 main.py path/to/invoice.jpg

# Check system status
python3 main.py --status

Pipeline Flow

data/input/invoice.jpg
    ↓ [OCR - minicpm-v]
data/ocr_output/invoice_data.txt
    ↓ [Mapper - Llama 3.2]
data/json_output/invoice.json
    ↓ [CRM Sync - Odoo]
Odoo Partner Record Created
    ↓ [Archive]
data/processed/invoice.jpg
    ↓ [Quality Report - After Batch]
report_db/reports/confidence_report_YYYYMMDD_HHMMSS.pdf

---

📁 Directory Structure

ocr-system/
├── main.py                      # Entry point - Run this!
├── invoice_schema.json          # JSON template for extracted data
├── requirements.txt             # Python dependencies
│
├── config/                      # Configuration
│   ├── __init__.py
│   └── settings.py              # All system settings (paths, models, CRM)
│
├── core/                        # Main processing modules
│   ├── __init__.py
│   ├── image_parser.py          # OCR: Image → Text
│   ├── mapper.py                # Mapper: Text → JSON (with auto-repair)
│   ├── crm_connector.py         # CRM: JSON → Odoo
│   └── main_controller.py       # Orchestrator: Manages entire pipeline
│
├── data/                        # Data directories
│   ├── input/                   # Drop invoices here to process
│   ├── ocr_output/              # Raw extracted text (debugging)
│   ├── json_output/             # Structured JSON data (final output)
│   └── processed/               # Auto-archived processed images
│
├── report_db/                   # Quality reporting & monitoring
│   ├── __init__.py
│   ├── calculate_extraction.py # Calculate confidence scores (0-100%)
│   ├── view_data.py             # View scores in terminal
│   ├── generate_pdf_report.py  # Generate color-coded PDF reports
│   └── reports/                 # Generated PDF reports (timestamped)
│
├── docker-compose.yml           # Odoo CRM deployment (optional)
└── setup_crm.py                 # Odoo CRM setup script

---

Configuration

All settings in config/settings.py:

Key Settings

# OCR Configuration
OCR_CONFIG = {
    "model_name": "minicpm-v",      # Vision model for OCR
    "ollama_url": "http://localhost:11434",
    "temperature": 0.1               # Low for deterministic output
}

# Mapper Configuration  
MAPPER_CONFIG = {
    "model_name": "llama3.2",        # LLM for intelligent extraction
    "temperature": 0.1               # Low for consistent JSON
}

# CRM Configuration (Optional)
CRM_CONFIG = {
    "url": "http://localhost:8069",
    "database": "odoo",
    "username": "admin",
    "password": "admin"
}

# Processing Options
PROCESSING_CONFIG = {
    "auto_archive": True,            # Move processed images to /processed
    "auto_sync_crm": True            # Automatically sync to Odoo
}

---

Usage Examples

1. Batch Processing

# Add multiple invoices to input folder
cp invoice*.jpg data/input/

# Run pipeline - processes all images
python3 main.py

# Output:
# ✓ Successfully processed 5/5 invoices
# ✓ Confidence scores calculated
# ✓ PDF report saved: report_db/reports/confidence_report_20231217_120000.pdf

2. Single Invoice Processing

python3 main.py data/input/invoice_001.jpg

# Output:
# ✓ Successfully processed: ORDER-12345

3. System Status Check

python3 main.py --status

# Output:
# Components:
#   • image_parser: ✓ Ready
#   • mapper: ✓ Ready  
#   • crm: ✓ Connected

4. Manual Quality Reports

# Calculate confidence scores
cd report_db
python3 calculate_extraction.py

# Generate PDF report
python3 generate_pdf_report.py

# View scores in terminal
python3 view_data.py

5. Using Components Programmatically

from core import ImageParser, InvoiceMapper, CRMConnector
from pathlib import Path

# OCR only
parser = ImageParser()
text = parser.process_image(Path("invoice.jpg"), save_output=True)

# Mapping only
mapper = InvoiceMapper()
data = mapper.process_text_file(Path("data/ocr_output/invoice_data.txt"))

# CRM sync only
crm = CRMConnector()
result = crm.sync_json_file(Path("data/json_output/invoice.json"))
print(f"Partner ID: {result['partner_id']}")

---

Output Data Structure

Extracted invoices follow this JSON schema (invoice_schema.json):

{
  "company_details": {
    "company_name": "ABC Corp"
  },
  "invoice_info": {
    "invoice_date": "2023-12-17",
    "invoice_time": "14:30:00",
    "order_no": "INV-2023-001",
    "order_date": "2023-12-15"
  },
  "vendor_details": {
    "vendor_name": "Supplier XYZ",
    "phone_no": "+1234567890",
    "email": "contact@supplier.com",
    "vendor_gst": "GST123456",
    "vendor_address": "123 Main St, City"
  },
  "buyer_details": { ... },
  "line_items": [
    {
      "product_name": "Product A",
      "quantity": 10,
      "total_value": 1000.00
    }
  ],
  "financials": {
    "total_bill": 1180.00,
    "mode_of_payment": "Credit",
    "tax_details": {
      "gst": 180.00,
      "sgst": 90.00,
      "cgst": 90.00,
      "igst": 0.00,
      "ugst": 0.00
    }
  }
}

---

📈 Quality Reporting

Confidence Scores

The system automatically calculates confidence scores (0-100%) based on:

• Number of filled fields vs expected fields (18 total)
• Scores stored in PostgreSQL for tracking
• Color-coded PDF reports:
  • 🟢 ≥80%: Excellent
  • 🟡 60-79%: Good
  • 🔴 <60%: Needs Review

PDF Report Features

• Summary statistics (average, highest, lowest scores)
• Detailed score table for each invoice
• Timestamped for version tracking
• Auto-generated after batch processing

---

Advanced Features

JSON Auto-Repair

The mapper includes intelligent JSON repair:

• Fixes trailing commas
• Balances unclosed brackets/braces
• 3-attempt retry with increasing temperature
• Detailed error logging with line numbers

Error Handling

• Graceful degradation (CRM failures don't break pipeline)
• Failed JSON responses saved for debugging
• Comprehensive logging at each stage
• Continue processing even if individual files fail

---

Optional: Deploy Odoo CRM

# Start Odoo + PostgreSQL via Docker
docker-compose up -d

# Setup Odoo for invoice management
python3 setup_crm.py

# Access Odoo web interface
open http://localhost:8069

---

Troubleshooting

Issue: "No module named 'ollama'"

pip install ollama requests

Issue: "connection to server failed"

# Check if Ollama is running
curl http://localhost:11434/api/tags

# Start Ollama if not running
ollama serve

Issue: "Failed to parse JSON"

• Check data/json_output/ for failed responses
• The system auto-retries 3 times with JSON repair
• Review logs for specific error details

Issue: "Database connection failed"

# Start PostgreSQL
brew services start postgresql  # macOS
sudo service postgresql start   # Linux

---

Requirements

Dependency	Version	Purpose
Python	3.8+	Runtime environment
ollama	latest	Access to vision & LLM models
requests	latest	HTTP API calls
Pillow	8.0+	Image processing
psycopg2-binary	latest	PostgreSQL database
fpdf2	latest	PDF report generation

---

How It Works

1. OCR Stage: Vision model (minicpm-v) reads invoice image and extracts raw text
2. Mapping Stage: Llama LLM intelligently extracts structured fields into JSON
3. Validation: Auto-repair fixes common JSON formatting issues
4. CRM Sync: Pushes data to Odoo partner records (optional)
5. Archive: Moves processed images to prevent reprocessing
6. Quality Report: Calculates scores and generates PDF (batch mode only)

chmod +x fresh_start.sh ./fresh_start.sh