https://github.com/zainibeats/weekly-receipt-tools
CLI tools for receipt workflows: build image grids, append receipt images to PDFs, and extract totals with a local vision model
https://github.com/zainibeats/weekly-receipt-tools
automation heic image-processing pdf python reciepts
Last synced: about 12 hours ago
JSON representation
CLI tools for receipt workflows: build image grids, append receipt images to PDFs, and extract totals with a local vision model
- Host: GitHub
- URL: https://github.com/zainibeats/weekly-receipt-tools
- Owner: zainibeats
- Created: 2026-06-02T06:28:59.000Z (28 days ago)
- Default Branch: main
- Last Pushed: 2026-06-11T08:21:49.000Z (18 days ago)
- Last Synced: 2026-06-11T10:13:56.762Z (18 days ago)
- Topics: automation, heic, image-processing, pdf, python, reciepts
- Language: Python
- Homepage:
- Size: 86.9 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Weekly Receipt Tools
> **Note**: This project contains AI-generated code
Separate command line tools for weekly receipt work:
- build a JPG grid from receipt images
- append a receipt image page to an expense-report PDF
- extract receipt dates and totals with a local vision LLM
The tools are intentionally separate. Use only the action needed for the current
step. Original images and PDFs are always preserved.
## Setup
```bash
python -m pip install -e ".[dev]"
```
Copy `.env.example` to `.env` and point it at your local AI server if you use
`receipt-process`.
## Menu Wrappers
For manual use without remembering commands, run the wrapper for your platform
from the project folder:
```bash
./run-image-pdf-tools.sh
```
On Windows, double-click `run-image-pdf-tools.bat`.
The wrappers create a local `.venv`, install `requirements.txt`, and show a
menu for making an image grid, appending an image to a PDF, or doing both in one
flow. They require Python 3.12 or 3.13.
## Tools
- [`scripts/make-image-grid.py`](docs/image-grid.md): combines HEIC, HEIF, JPG,
JPEG, and PNG images into one balanced JPG grid.
- [`scripts/append-image-page.py`](docs/append-image-page.md): appends a
JPG/JPEG image as a US Letter page at the end of an existing PDF.
- [`receipt-process`](docs/receipt-processor.md): extracts receipt dates and
totals from HEIC, HEIF, JPG, JPEG, PNG, TIFF, BMP, and WebP images with a
configured local vision model.
## Quick Examples
```bash
python scripts/make-image-grid.py ~/Pictures/receipts
python scripts/append-image-page.py ~/Pictures/receipts/image-grid.jpg --pdf ~/Downloads/input.pdf
receipt-process ~/Pictures/receipts
```
## Project Docs
- [Image grid usage](docs/image-grid.md)
- [Append image to PDF usage](docs/append-image-page.md)
- [Receipt processor usage](docs/receipt-processor.md)
- [Receipt processor internals](docs/receipt-processor-internals.md)
## Tests
```bash
python -m pytest
```