| Name | receipt-ocr JSON |
| Version |
0.2.0
JSON |
| download |
| home_page | None |
| Summary | A package for extracting structured data from receipts. |
| upload_time | 2025-08-24 19:57:03 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.9 |
| 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. |
| keywords |
llm
ocr
receipts
tesseract
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Receipt OCR Engine
An efficient OCR engine for receipt image processing.
This repository provides a comprehensive solution for Optical Character Recognition (OCR) on receipt images, featuring both a dedicated Tesseract OCR module and a general receipt processing package using LLMs.
## 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>
## Project Structure
The project is organized into two main modules:
- **`src/receipt_ocr/`**: A new package for abstracting general receipt processing logic, including CLI, parsers, prompts, and providers for various LLM services.
- **`src/tesseract_ocr/`**: Contains the Tesseract OCR FastAPI application, CLI, utility functions, and Docker setup for performing OCR.
## Prerequisites
- Python 3.x
- Docker (for running Tesseract OCR as a service)
- Docker-compose (for running Tesseract OCR as a service)
- Tesseract OCR (for local Tesseract CLI usage) - [Installation Guide](https://tesseract-ocr.github.io/tessdoc/Installation.html)
## Usage Examples
### Receipt OCR Module
This module provides a higher-level abstraction for processing receipts, leveraging LLMs for parsing and extraction.
To use the `receipt-ocr` CLI, first install it:
```bash
pip install receipt-ocr
```
1. **Configure Environment Variables:**
Create a `.env` file in the project root or set environment variables directly. This module supports multiple LLM providers.
Example `.env` for OpenAI:
> Get it from here: http://platform.openai.com/api-keys
```
OPENAI_API_KEY="your_openai_api_key_here"
OPENAI_MODEL="gpt-4.1"
```
Example `.env` for Gemini:
> Get it from here: https://aistudio.google.com/app/apikey
```
OPENAI_API_KEY="your_gemini_api_key_here"
OPENAI_BASE_URL="https://generativelanguage.googleapis.com/v1beta/openai/"
OPENAI_MODEL="gemini-2.5-pro"
```
Example `.env` for Groq:
> Get it from here: https://console.groq.com/keys
```
OPENAI_API_KEY="your_groq_api_key_here"
OPENAI_BASE_URL="https://api.groq.com/openai/v1/models"
OPENAI_MODEL="llama3-8b-8192"
```
2. **Process a receipt using the `receipt-ocr` CLI:**
```bash
receipt-ocr images/receipt.jpg
```
This command will use the configured LLM provider to extract structured data from the receipt image.
> sample output
```json
{
"merchant_name": "Saathimart.com",
"merchant_address": "Narephat, Kathmandu",
"transaction_date": "2024-05-07",
"transaction_time": "09:09:00",
"total_amount": 185.0,
"line_items": [
{
"item_name": "COLGATE DENTAL",
"item_quantity": 1,
"item_price": 95.0,
"item_total": 95.0
},
{
"item_name": "PATANJALI ANTI",
"item_quantity": 1,
"item_price": 70.0,
"item_total": 70.0
},
{
"item_name": "GODREJ NO 1 SOAP",
"item_quantity": 1,
"item_price": 20.0,
"item_total": 20.0
}
]
}
```
### Tesseract OCR Module
This module provides direct OCR capabilities using Tesseract. For more detailed local setup and usage, refer to [`src/tesseract_ocr/README.md`](src/tesseract_ocr/README.md).
1. **Run Tesseract OCR locally via CLI:**
```bash
python src/tesseract_ocr/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">
2. **Run Tesseract OCR as a Docker service:**
```bash
docker-compose -f src/tesseract_ocr/docker-compose.yml 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:**
- **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'
```
## Contributing
We welcome contributions to the Receipt OCR Engine! To contribute, please follow these steps:
1. **Fork the repository** and clone it to your local machine.
2. **Create a new branch** for your feature or bug fix.
3. **Set up your development environment**:
```bash
# Navigate to the project root
cd receipt-ocr
# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh # OR pip install uv
# Create and activate a virtual environment
uv venv --python=3.12
source .venv/bin/activate # For Windows, use .venv\Scripts\activate
# Install development and test dependencies
uv sync --all-extras --dev
uv pip install -r src/tesseract_ocr/requirements.txt
uv pip install -e.
```
4. **Make your changes** and ensure they adhere to the project's coding style.
5. **Run tests** to ensure your changes haven't introduced any regressions:
```bash
uv run pytest
```
6. **Run linting and formatting checks**:
```bash
uvx ruff check .
uvx ruff format .
```
7. **Commit your changes** with a clear and concise commit message.
8. **Push your branch** to your forked repository.
9. **Open a Pull Request** to the `main` branch of the upstream repository, describing your changes in detail.
## LinkedIn Post
- Gemini Docs: https://ai.google.dev/tutorials/python_quickstart
- LinkedIn Post: https://www.linkedin.com/feed/update/urn:li:activity:7145860319150505984/
## 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/)
Raw data
{
"_id": null,
"home_page": null,
"name": "receipt-ocr",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "llm, ocr, receipts, tesseract",
"author": null,
"author_email": "Bhimraj Yadav <bhimrajyadav977@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/c7/06/c0183a2352785380a020f3a3fc620e1c668854c2d3c147fba301b9d40fbd/receipt_ocr-0.2.0.tar.gz",
"platform": null,
"description": "# Receipt OCR Engine\n\nAn efficient OCR engine for receipt image processing.\n\nThis repository provides a comprehensive solution for Optical Character Recognition (OCR) on receipt images, featuring both a dedicated Tesseract OCR module and a general receipt processing package using LLMs.\n\n\n\n## Star History\n\n<a href=\"https://star-history.com/#bhimrazy/receipt-ocr&Date\">\n <picture>\n <source media=\"(prefers-color-scheme: dark)\" srcset=\"https://api.star-history.com/svg?repos=bhimrazy/receipt-ocr&type=Date&theme=dark\" />\n <source media=\"(prefers-color-scheme: light)\" srcset=\"https://api.star-history.com/svg?repos=bhimrazy/receipt-ocr&type=Date\" />\n <img alt=\"Star History Chart\" src=\"https://api.star-history.com/svg?repos=bhimrazy/receipt-ocr&type=Date\" />\n </picture>\n</a>\n\n## Project Structure\n\nThe project is organized into two main modules:\n\n- **`src/receipt_ocr/`**: A new package for abstracting general receipt processing logic, including CLI, parsers, prompts, and providers for various LLM services.\n- **`src/tesseract_ocr/`**: Contains the Tesseract OCR FastAPI application, CLI, utility functions, and Docker setup for performing OCR.\n\n## Prerequisites\n\n- Python 3.x\n- Docker (for running Tesseract OCR as a service)\n- Docker-compose (for running Tesseract OCR as a service)\n- Tesseract OCR (for local Tesseract CLI usage) - [Installation Guide](https://tesseract-ocr.github.io/tessdoc/Installation.html)\n\n## Usage Examples\n\n### Receipt OCR Module\n\nThis module provides a higher-level abstraction for processing receipts, leveraging LLMs for parsing and extraction.\n\nTo use the `receipt-ocr` CLI, first install it:\n\n```bash\npip install receipt-ocr\n```\n\n1. **Configure Environment Variables:**\n Create a `.env` file in the project root or set environment variables directly. This module supports multiple LLM providers.\n\n Example `.env` for OpenAI:\n\n > Get it from here: http://platform.openai.com/api-keys\n\n ```\n OPENAI_API_KEY=\"your_openai_api_key_here\"\n OPENAI_MODEL=\"gpt-4.1\"\n ```\n\n Example `.env` for Gemini:\n\n > Get it from here: https://aistudio.google.com/app/apikey\n\n ```\n OPENAI_API_KEY=\"your_gemini_api_key_here\"\n OPENAI_BASE_URL=\"https://generativelanguage.googleapis.com/v1beta/openai/\"\n OPENAI_MODEL=\"gemini-2.5-pro\"\n ```\n\n Example `.env` for Groq:\n\n > Get it from here: https://console.groq.com/keys\n\n ```\n OPENAI_API_KEY=\"your_groq_api_key_here\"\n OPENAI_BASE_URL=\"https://api.groq.com/openai/v1/models\"\n OPENAI_MODEL=\"llama3-8b-8192\"\n ```\n\n2. **Process a receipt using the `receipt-ocr` CLI:**\n\n ```bash\n receipt-ocr images/receipt.jpg\n ```\n\n This command will use the configured LLM provider to extract structured data from the receipt image.\n\n > sample output\n\n ```json\n {\n \"merchant_name\": \"Saathimart.com\",\n \"merchant_address\": \"Narephat, Kathmandu\",\n \"transaction_date\": \"2024-05-07\",\n \"transaction_time\": \"09:09:00\",\n \"total_amount\": 185.0,\n \"line_items\": [\n {\n \"item_name\": \"COLGATE DENTAL\",\n \"item_quantity\": 1,\n \"item_price\": 95.0,\n \"item_total\": 95.0\n },\n {\n \"item_name\": \"PATANJALI ANTI\",\n \"item_quantity\": 1,\n \"item_price\": 70.0,\n \"item_total\": 70.0\n },\n {\n \"item_name\": \"GODREJ NO 1 SOAP\",\n \"item_quantity\": 1,\n \"item_price\": 20.0,\n \"item_total\": 20.0\n }\n ]\n }\n ```\n\n### Tesseract OCR Module\n\nThis module provides direct OCR capabilities using Tesseract. For more detailed local setup and usage, refer to [`src/tesseract_ocr/README.md`](src/tesseract_ocr/README.md).\n\n1. **Run Tesseract OCR locally via CLI:**\n\n ```bash\n python src/tesseract_ocr/main.py -i images/receipt.jpg\n ```\n\n Replace `images/receipt.jpg` with the path to your receipt image.\n\n > Please ensure that the image is well-lit and that the edges of the receipt are clearly visible and detectable within the image.\n > <img src=\"https://github.com/bhimrazy/receipt-ocr/assets/46085301/2ea009f0-9e15-42b2-9f15-063a8ec169f1\" alt=\"Receipt Image\" width=\"300\" height=\"400\">\n\n2. **Run Tesseract OCR as a Docker service:**\n\n ```bash\n docker-compose -f src/tesseract_ocr/docker-compose.yml up\n ```\n\n 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.\n\n **API Endpoint:**\n\n - **POST** `/ocr/`: Upload a receipt image file to perform OCR. The response will contain the extracted text from the receipt.\n\n **Example usage with cURL:**\n\n ```bash\n curl -X 'POST' \\\n 'http://localhost:8000/ocr/' \\\n -H 'accept: application/json' \\\n -H 'Content-Type: multipart/form-data' \\\n -F 'file=@images/paper-cash-sell-receipt-vector-23876532.jpg;type=image/jpeg'\n ```\n\n## Contributing\n\nWe welcome contributions to the Receipt OCR Engine! To contribute, please follow these steps:\n\n1. **Fork the repository** and clone it to your local machine.\n2. **Create a new branch** for your feature or bug fix.\n3. **Set up your development environment**:\n\n ```bash\n # Navigate to the project root\n cd receipt-ocr\n\n # Install uv\n curl -LsSf https://astral.sh/uv/install.sh | sh # OR pip install uv\n\n # Create and activate a virtual environment\n uv venv --python=3.12\n source .venv/bin/activate # For Windows, use .venv\\Scripts\\activate\n\n # Install development and test dependencies\n uv sync --all-extras --dev\n uv pip install -r src/tesseract_ocr/requirements.txt\n uv pip install -e.\n ```\n\n4. **Make your changes** and ensure they adhere to the project's coding style.\n5. **Run tests** to ensure your changes haven't introduced any regressions:\n ```bash\n uv run pytest\n ```\n6. **Run linting and formatting checks**:\n ```bash\n uvx ruff check .\n uvx ruff format .\n ```\n7. **Commit your changes** with a clear and concise commit message.\n8. **Push your branch** to your forked repository.\n9. **Open a Pull Request** to the `main` branch of the upstream repository, describing your changes in detail.\n\n## LinkedIn Post\n\n- Gemini Docs: https://ai.google.dev/tutorials/python_quickstart\n- LinkedIn Post: https://www.linkedin.com/feed/update/urn:li:activity:7145860319150505984/\n\n\n\n## License\n\nThis project is licensed under the terms of the MIT license.\n\n## References\n\n- [Automatically OCR\u2019ing Receipts and Scans](https://pyimagesearch.com/2021/10/27/automatically-ocring-receipts-and-scans/)\n",
"bugtrack_url": null,
"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.",
"summary": "A package for extracting structured data from receipts.",
"version": "0.2.0",
"project_urls": {
"Bug Tracker": "https://github.com/bhimrazy/receipt-ocr/issues",
"Documentation": "https://github.com/bhimrazy/receipt-ocr",
"Download": "https://github.com/bhimrazy/receipt-ocr",
"Homepage": "https://github.com/bhimrazy/receipt-ocr",
"Source Code": "https://github.com/bhimrazy/receipt-ocr"
},
"split_keywords": [
"llm",
" ocr",
" receipts",
" tesseract"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "bb3f2506e1aec1f6faeb1fa8b8422cbe34f85285c2bef398f2e725da77948dd4",
"md5": "1b03eb7ae4bb461d5e2bea86ed52d42d",
"sha256": "b89073f22f10ea9a54b18707f589d9c8fc96f5c95b57abc70d2c3d2f2754823a"
},
"downloads": -1,
"filename": "receipt_ocr-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1b03eb7ae4bb461d5e2bea86ed52d42d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 9403,
"upload_time": "2025-08-24T19:57:02",
"upload_time_iso_8601": "2025-08-24T19:57:02.257850Z",
"url": "https://files.pythonhosted.org/packages/bb/3f/2506e1aec1f6faeb1fa8b8422cbe34f85285c2bef398f2e725da77948dd4/receipt_ocr-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "c706c0183a2352785380a020f3a3fc620e1c668854c2d3c147fba301b9d40fbd",
"md5": "7477cd915dbb89fe70581a5e7f9320f2",
"sha256": "7f1bbd9ba52225e7c0615ba90b1f3d9ae2aa8f61a41a075262123a9e8723da1c"
},
"downloads": -1,
"filename": "receipt_ocr-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "7477cd915dbb89fe70581a5e7f9320f2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 2020380,
"upload_time": "2025-08-24T19:57:03",
"upload_time_iso_8601": "2025-08-24T19:57:03.918217Z",
"url": "https://files.pythonhosted.org/packages/c7/06/c0183a2352785380a020f3a3fc620e1c668854c2d3c147fba301b9d40fbd/receipt_ocr-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-24 19:57:03",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "bhimrazy",
"github_project": "receipt-ocr",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "receipt-ocr"
}
