A modern, object-oriented Streamlit web application that uses state-of-the-art Open Source Vision models (like Qwen2.5-VL) via Hugging Face's Inference API to extract structured data from grocery receipts.
✨ Features
Multimodal OCR: Upload receipt images (JPG/PNG) and automatically extract the Store Name, Date, itemized purchases (with quantity, price, and discounts), and Totals into a structured JSON pipeline.
Hugging Face Native: Uses the huggingface_hub Inference Client for robust routing, supporting both free Serverless models and custom Dedicated Endpoints.
Dynamic Configuration: Change out models on the fly through the UI sidebar.
Clean UI Analytics: Auto-formats extracted data into beautiful dataframes and metric highlights.
Secure Handling: Excludes API tokens from the repository securely via .env.
🚀 How to Run Locally
1. Prerequisites
Ensure you have Python 3.9+ installed. You will also need a Hugging Face Token with Inference permissions.
Create a file named .env in the root of the project folder:
HF_TOKEN=your_huggingface_token_here
(The .gitignore file guarantees this is never accidentally uploaded to your public repository!)
4. Launch the App!
streamlit run app.py
Open up your browser to the URL provided in the terminal (usually http://localhost:8501) to start scanning!
🛠️ Modularity and Architecture
This app follows a clean Object-Oriented design pattern:
backend.py: Contains the ReceiptOCRClient responsible for communicating with the Hugging Face Serverless endpoint, base64 encoding, and cleanly structuring model prompts. Isolated purely to API logic.
app.py: Contains the ReceiptParserApp governing the Streamlit User Interface, session state manipulation, and error rendering.
🤖 Models & DeepSeek Note
By default, the Streamlit sidebar is populated with Qwen/Qwen2.5-VL-7B-Instruct.
While the prompt mentions DeepSeek models, the free Hugging Face Serverless Inference Router does not natively host massive DeepSeek Vision models (like deepseek-vl2). If you require an exclusive DeepSeek model pipeline:
Spin up a Dedicated Endpoint for DeepSeek through your Hugging Face space.
In the App UI Sidebar, paste your custom Endpoint URL inside the API Base URL field!
