receipt-ocr 0.1.0__py3-none-any.whl

receipt_ocr-0.1.0.dist-info/METADATA

@@ -0,0 +1,154 @@
+Metadata-Version: 2.4
+Name: receipt-ocr
+Version: 0.1.0
+Summary: A package for extracting structured data from receipts.
+Project-URL: Homepage, https://github.com/bhimrazy/receipt-ocr
+Project-URL: Bug Tracker, https://github.com/bhimrazy/receipt-ocr/issues
+Project-URL: Documentation, https://github.com/bhimrazy/receipt-ocr
+Project-URL: Source Code, https://github.com/bhimrazy/receipt-ocr
+Project-URL: Download, https://github.com/bhimrazy/receipt-ocr
+Author-email: Bhimraj Yadav <bhimrajyadav977@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2025 Bhimraj Yadav
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: llm,ocr,receipts,tesseract
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Requires-Dist: openai
+Requires-Dist: pillow
+Requires-Dist: python-dotenv
+Description-Content-Type: text/markdown
+
+# Receipt OCR Engine
+
+This repository hosts a script and a Docker-compose setup for performing Optical Character Recognition (OCR) on receipt images.
+
+![image](https://github.com/bhimrazy/receipt-ocr/assets/46085301/305df68d-50d8-41d4-81d0-9324966fb6c9)
+
+## Star History
+
+<a href="https://star-history.com/#bhimrazy/receipt-ocr&Date">
+ <picture>
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=bhimrazy/receipt-ocr&type=Date&theme=dark" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=bhimrazy/receipt-ocr&type=Date" />
+   <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=bhimrazy/receipt-ocr&type=Date" />
+ </picture>
+</a>
+
+## Prerequisites
+
+- Python 3.x
+- Docker
+- Docker-compose
+
+## Installation
+
+### Clone the repository
+
+```bash
+git clone https://github.com/bhimrazy/receipt-ocr.git
+cd receipt-ocr
+```
+
+### Set up Python environment (if not using Docker)
+- Install [tesseract](https://tesseract-ocr.github.io/tessdoc/Installation.html)
+
+```bash
+# Create and activate a virtual environment (optional but recommended)
+python -m venv venv
+source venv/bin/activate  # For Windows, use venv\Scripts\activate
+
+# Install dependencies
+pip install -r requirements.txt
+```
+
+## Usage
+
+### Running the script locally
+
+#### `main.py`
+
+The `main.py` script performs OCR on an input image of a receipt.
+
+```bash
+python main.py -i images/receipt.jpg
+```
+
+Replace `images/receipt.jpg` with the path to your receipt image.
+>Please ensure that the image is well-lit and that the edges of the receipt are clearly visible and detectable within the image.
+<img src="https://github.com/bhimrazy/receipt-ocr/assets/46085301/2ea009f0-9e15-42b2-9f15-063a8ec169f1" alt="Receipt Image" width="300" height="400">
+
+
+### Using Docker-compose
+
+The repository includes a Docker-compose setup for running the OCR engine as a service.
+
+```bash
+docker-compose up
+```
+
+Once the service is up and running, you can perform OCR on receipt images by sending a POST request to `http://localhost:8000/ocr/` with the image file.
+
+## API Endpoint
+
+The OCR functionality can be accessed via a FastAPI endpoint:
+
+- **POST** `/ocr/`: Upload a receipt image file to perform OCR. The response will contain the extracted text from the receipt.
+
+Example usage with cURL:
+
+```bash
+curl -X 'POST' \
+  'http://localhost:8000/ocr/' \
+  -H 'accept: application/json' \
+  -H 'Content-Type: multipart/form-data' \
+  -F 'file=@images/paper-cash-sell-receipt-vector-23876532.jpg;type=image/jpeg'
+```
+
+## Using Gemini
+- Gemini Docs:https://ai.google.dev/tutorials/python_quickstart
+- LinkedIn Post: https://www.linkedin.com/feed/update/urn:li:activity:7145860319150505984/
+  
+![image](https://github.com/bhimrazy/receipt-ocr/assets/46085301/ee4a0c82-f134-4a19-a275-93a59c7503b8)
+
+
+## License
+
+This project is licensed under the terms of the MIT license.
+
+## References
+- [Automatically OCR’ing Receipts and Scans](https://pyimagesearch.com/2021/10/27/automatically-ocring-receipts-and-scans/)
+
+

receipt_ocr-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+src/receipt_ocr/__about__.py,sha256=JiuulFAhKiGdiLlzpmDNzxQworwYN36usDdY_HrWAJg,447
+src/receipt_ocr/__init__.py,sha256=nTXoT7OD7yo_j08DAsMF_SwbrcInLz6sNcmxRozErfE,189
+src/receipt_ocr/cli.py,sha256=QtxZisXzlXEyIDMhCXUcVWwb5Hjb5uUYGmQ7f1Fgsvc,2525
+src/receipt_ocr/parsers.py,sha256=IZriFyabV_YHSguUv72g7zdaBeiFPm7g7uoUsF7tk5Y,718
+src/receipt_ocr/prompts.py,sha256=FBFxnxzlwqcZcDZ1pDhYmm5Ctculu12ldd5PR6VhPaA,861
+src/receipt_ocr/providers.py,sha256=BtWMbu6CeJdILcQN2tKLizvPkYY8BV6XOdzpaBAfE3M,2098
+receipt_ocr-0.1.0.dist-info/METADATA,sha256=gesai8yaMde8J8sWhHBa19yKXu7OBC_VOzyRxX6E5P8,5730
+receipt_ocr-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+receipt_ocr-0.1.0.dist-info/entry_points.txt,sha256=DH35VJcOutisJ4FWujHU0XMrXVH0LDEdNQXLNwzn9ls,53
+receipt_ocr-0.1.0.dist-info/licenses/LICENSE,sha256=aUC5PJ0cU7_TKITWsk1r5CFZJQ8s1di8pZlMG3sNUao,1069
+receipt_ocr-0.1.0.dist-info/RECORD,,

receipt_ocr-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

receipt_ocr-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+receipt-ocr = receipt_ocr.cli:main

receipt_ocr-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Bhimraj Yadav
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

src/receipt_ocr/__about__.py

@@ -0,0 +1,17 @@
+__version__ = "0.1.0"
+__docs__ = "A package for extracting structured data from receipts."
+__author__ = "Bhimraj Yadav"
+__author_email__ = "bhimrajyadav977@gmail.com"
+__license__ = "MIT"
+__copyright__ = "Copyright (c) 2025 Bhimraj Yadav"
+__homepage__ = "https://github.com/bhimrazy/receipt-ocr"
+
+__all__ = [
+    "__author__",
+    "__author_email__",
+    "__copyright__",
+    "__docs__",
+    "__homepage__",
+    "__license__",
+    "__version__",
+]

src/receipt_ocr/__init__.py

@@ -0,0 +1,9 @@
+from .cli import ReceiptProcessor
+from .parsers import ReceiptParser
+from .providers import OpenAIProvider
+
+__all__ = [
+    "ReceiptProcessor",
+    "OpenAIProvider",
+    "ReceiptParser",
+]

src/receipt_ocr/cli.py

@@ -0,0 +1,89 @@
+import argparse
+import os
+import json
+from .providers import OpenAIProvider
+from .parsers import ReceiptParser
+from dotenv import load_dotenv
+
+load_dotenv()
+
+
+class ReceiptProcessor:
+    """
+    Process a receipt image and return a structured JSON object.
+    """
+
+    def __init__(self, provider, parser):
+        """
+        Initialize the receipt processor.
+        """
+        self.provider = provider
+        self.parser = parser
+
+    def process_receipt(self, image_path: str, json_schema: dict, model: str) -> dict:
+        """
+        Process a receipt image and return a structured JSON object.
+        """
+        response = self.provider.get_response(image_path, json_schema, model)
+        return self.parser.parse(response)
+
+
+def main():
+    """
+    Main function for the CLI.
+    """
+    parser = argparse.ArgumentParser(
+        description="Extract information from a receipt image."
+    )
+    parser.add_argument("image_path", type=str, help="The path to the receipt image.")
+    parser.add_argument(
+        "--schema_path", type=str, help="The path to a custom JSON schema file."
+    )
+    parser.add_argument(
+        "--model",
+        type=str,
+        default="gpt-4-vision-preview",
+        help="The model to use for the LLM.",
+    )
+    parser.add_argument("--api_key", type=str, help="The API key for the LLM provider.")
+    parser.add_argument(
+        "--base_url", type=str, help="The base URL for the LLM provider."
+    )
+    args = parser.parse_args()
+
+    # Load the JSON schema
+    if args.schema_path:
+        with open(args.schema_path, "r") as f:
+            json_schema = json.load(f)
+    else:
+        json_schema = {
+            "merchant_name": "string",
+            "merchant_address": "string",
+            "transaction_date": "string",
+            "transaction_time": "string",
+            "total_amount": "number",
+            "line_items": [
+                {
+                    "item_name": "string",
+                    "item_quantity": "number",
+                    "item_price": "number",
+                }
+            ],
+        }
+
+    # Initialize the provider and parser
+    provider = OpenAIProvider(api_key=args.api_key, base_url=args.base_url)
+    parser = ReceiptParser()
+
+    # Initialize the processor
+    processor = ReceiptProcessor(provider, parser)
+
+    # Process the receipt
+    result = processor.process_receipt(args.image_path, json_schema, args.model)
+
+    # Print the result
+    print(json.dumps(result, indent=4))
+
+
+if __name__ == "__main__":
+    main()

src/receipt_ocr/parsers.py

@@ -0,0 +1,23 @@
+import json
+
+
+class ReceiptParser:
+    """
+    Parser for the LLM's response.
+    """
+
+    def parse(self, response: str) -> dict:
+        """
+        Parse the LLM's response and return a JSON object.
+        """
+        try:
+            # The response is often wrapped in a code block
+            response = response.strip()
+            if response.startswith("```json"):
+                response = response[7:-4]
+            elif response.startswith("```"):
+                response = response[3:-3]
+            return json.loads(response)
+        except json.JSONDecodeError:
+            # Handle the case where the response is not valid JSON
+            return {"error": "The LLM's response was not valid JSON."}

src/receipt_ocr/prompts.py

@@ -0,0 +1,35 @@
+SYSTEM_PROMPT = """
+You are a world-class receipt processing expert. Your task is to accurately extract information from a receipt image and provide it in a structured JSON format.
+
+Here is an example of a desired JSON output:
+
+```json
+{{
+  "merchant_name": "Example Store",
+  "merchant_address": "123 Main St, Anytown, USA 12345",
+  "transaction_date": "2023-01-01",
+  "transaction_time": "12:34:56",
+  "total_amount": 75.50,
+  "line_items": [
+    {{
+      "item_name": "Item 1",
+      "item_quantity": 2,
+      "item_price": 20.00
+    }},
+    {{
+      "item_name": "Item 2",
+      "item_quantity": 1,
+      "item_price": 35.50
+    }}
+  ]
+}}
+```
+
+Please extract the information from the receipt image and provide it in the following JSON schema:
+
+```json
+{{json_schema_content}}
+```
+"""
+
+USER_PROMPT = "Please extract the information from this receipt image."

src/receipt_ocr/providers.py

@@ -0,0 +1,73 @@
+import os
+from abc import ABC, abstractmethod
+from openai import OpenAI
+from PIL import Image
+import base64
+import io
+import json
+from .prompts import SYSTEM_PROMPT, USER_PROMPT
+
+
+class LLMProvider(ABC):
+    """
+    Abstract base class for LLM providers.
+    """
+
+    @abstractmethod
+    def get_response(self, image_path: str, json_schema: dict, model: str) -> str:
+        """
+        Get the response from the LLM provider.
+        """
+        pass
+
+
+class OpenAIProvider(LLMProvider):
+    """
+    LLM provider for OpenAI-compatible APIs.
+    """
+
+    def __init__(self, api_key: str = None, base_url: str = None):
+        """
+        Initialize the OpenAI provider.
+        """
+        self.api_key = api_key or os.getenv("OPENAI_API_KEY")
+        self.base_url = base_url or os.getenv("OPENAI_BASE_URL")
+        self.client = OpenAI(api_key=self.api_key, base_url=self.base_url)
+
+    def get_response(self, image_path: str, json_schema: dict, model: str) -> str:
+        """
+        Get the response from the OpenAI API.
+        """
+        # Load the image
+        image = Image.open(image_path)
+
+        # Convert the image to base64
+        buffered = io.BytesIO()
+        image.save(buffered, format="PNG")
+        img_str = base64.b64encode(buffered.getvalue()).decode("utf-8")
+
+        # Create the system prompt
+        system_prompt = SYSTEM_PROMPT
+
+        response = self.client.chat.completions.create(
+            model=model,
+            response_format={"type": "json_object"},
+            messages=[
+                {
+                    "role": "system",
+                    "content": system_prompt,
+                },
+                {
+                    "role": "user",
+                    "content": [
+                        {"type": "text", "text": USER_PROMPT},
+                        {
+                            "type": "image_url",
+                            "image_url": {"url": f"data:image/png;base64,{img_str}"},
+                        },
+                    ],
+                },
+            ],
+        )
+
+        return response.choices[0].message.content