🧠 Business Intelligence OCR

An advanced, high-performance, and local Document Processing Pipeline designed to extract strategic structured data from images (invoices, contracts, receipts, and more). This project combines Local Computer Vision, Large Language Models (LLMs), Asynchronous Processing, and an Active Database Cache to deliver instant results while protecting data privacy and optimizing local hardware resources.

---

🚀 Project Overview

The Business Intelligence OCR is a local document intelligence ecosystem. When a user uploads a batch of images, the pipeline instantly calculates a digital cryptographic signature (SHA-256 Hash) for each file and checks a PostgreSQL database.

• Cache Hit: If the document has been processed before, the structured JSON data is recovered instantly from the database (0ms GPU cost).
• Cache Miss: If it is a new document, the system queues the file into an asynchronous pipeline. To prevent Video RAM (VRAM) bottlenecks on local hardware, a strict Asyncio Semaphore acts as a traffic controller, allowing only one concurrent GPU job at a time while keeping the UI responsive and processing non-blocking operations in the background.

---

🛠️ Built With

This project relies on a robust stack designed for performance, reusability, and local execution:

• Python 3.12 – Core language utilizing asynchronous programming (asyncio, threads).
• Streamlit – A reactive, modern web frontend built with custom glassmorphic HTML/CSS and real-time status card rendering.
• Docker PostgreSQL Image – Containerized local database used as an ultra-fast document cache via a JSONB index.
• Docker & Docker Compose – Containerization for seamless database deployment.
• Ollama – Engine for hosting and serving local state-of-the-art AI models.
• GLM-OCR – Specialized local Vision-Language Model used for raw optical character recognition.
• Qwen 2.5 (1.5B) – Used for grammatical correction and structural cleanup of the raw OCR text.
• IBM Granite 4.1 (3B) – Specialized lightweight model configured to output strict, structured B2B JSON payloads.

---

💾 Hardware & VRAM Requirements

Running three local AI models simultaneously requires dedicated graphics memory.

• Standard Setup: The default configuration using glm-ocr, qwen2.5:1.5b, and granite4.1:3b consumes approximately 8 to 10 GB of VRAM.
• Budget/Lower-Spec Setup: If your GPU has less than 8GB of VRAM, you can easily swap the processing models in your ia_service.py to smaller alternatives (such as moondream for OCR, or micro-parameters of Qwen/Llama) to make it run smoothly on inferior graphics cards.

---

📊 Application Interface

Below are visual highlights of how the batch processor works in real-time.

• 📥 Upload and Real-Time Batch Processing Status

• 

• ⚡ Structured Output & Metadata Extraction

  

• 📜 Database Index Cache & Analytical Insights

  

---

🧠 Technical Hurdles & Challenges Faced

Building a locally hosted AI engine comes with unique engineering challenges. Here are the key obstacles tackled during development:

1. VRAM Constraints & Local GPU Bottlenecks: Local execution of Vision Models and LLMs simultaneously is highly resource-intensive. Running multiple batch files concurrently caused Out-Of-Memory (OOM) GPU crashes.
   • Solution: Integrated a strict asyncio.Semaphore(1) gatekeeper. This forces the GPU to run only one active inference at a time, while non-blocking tasks (like calculating hashes and querying Postgres) continue running concurrently.
2. Web UI UI Repainting & Cascading Elements: Streamlit is designed to re-render the entire page upon state changes, which originally caused processed status cards to duplicate and cascade infinitely down the screen.
   • Solution: Implemented st.session_state coupled with a single st.empty() container. The entire card list is generated as a unified HTML block and dynamically swapped, keeping the UI static, beautiful, and reactive.
3. Strict JSON Structuring on Lightweight Models: Smaller models (like Granite 3B) can sometimes hallucinate or include conversational markdown wrappers (like ```json) which breaks application parsers.
   • Solution: Tailored explicit system prompt guidelines combined with Ollama's native format="json" option, wrapping outputs with strict error-handling json.loads fallbacks in Python.

---

💻 Local Installation & Setup Guide

This project is fully supported on Windows and Linux distributions. (It should theoretically work on macOS, provided your local Docker and Ollama GPU-acceleration configurations match).

📋 Prerequisites

Before starting, ensure you have the following installed on your machine:

• Python 3.12
• Docker Desktop
• Ollama Desktop App (Must be installed and running on your local OS)

---

⚙️ Step-by-Step Installation

1. Clone the Repository

git clone [https://github.com/diegormirhan/intelligence-ocr.git](https://github.com/diegormirhan/intelligence-ocr.git)
cd intelligence-ocr

2. Install Python Dependencies

Set up a virtual environment and install the required modules:

# Windows
python -m venv venv
venv\Scripts\activate

# Linux / macOS
python3 -m venv venv
source venv/bin/activate

pip install -r requirements.txt

3. Spin up the Postgres Database (Docker)

The system uses PostgreSQL as its active cache database. We package this inside a lightweight Docker container. Run the following command to start the database in the background:

docker-compose up -d

What does Docker Compose do here? It spins up an isolated Postgres 16 instance, exposes port 5432, maps a local volume to persist your cache logs even if the container stops, and configures the default database credentials.

4. Prepare Local AI Models (Ollama)

Ensure your native Ollama desktop application is running. Open your terminal and pull the models used in the pipeline:

# Model for OCR vision tasks
ollama run glm-ocr

# Model for grammatical correction
ollama pull qwen2.5:1.5b

# Model for structured JSON generation
ollama pull granite4.1:3b

5. Launch the Streamlit Interface

Once the database is up and models are pulled, start the web interface:

streamlit run app.py

Open your browser and navigate to the local address displayed in your terminal (usually http://localhost:8501). You are now ready to process batches of documents completely offline!