This is a submission for the Hacktoberfest Open-Source AI Challenge Week 2: Side Hustle
receipt-sorter is a command-line tool that turns a messy folder of receipts and invoices (PDFs and phone photos) into something an accountant can use. It renames each file (2026-10-14_Brew-Bean-Cafe_441.0.png), writes an accountant-ready receipts.csv (date, vendor, total, tax, currency, category), and produces a summary.md with totals per category.
Who would pay for it: freelancers, consultants and tiny agencies who dread tax season and handle other people's financial documents. Their problem is twofold: the sorting is tedious, and they don't want client invoices and bank details uploaded to a third-party cloud. A tool that runs entirely on their own laptop solves both.
Drop a folder of receipts and invoices (PDFs and phone photos) in, get back renamed files
an accountant-ready receipts.csv, and a category summary. A local open-weight vision model
does the reading, so client invoices and bank details never leave your laptop.
sorted_output/
sorted/ 2026-03-04_Figma_15.0.pdf ... (confident results)
needs_review/ anything unreadable, low-confidence or possibly duplicated
receipts.csv date, vendor, total, tax, currency, category, notes ...
summary.md totals per currency and category + a review list
Originals are copied, never moved or modified.
ollama pull qwen2.5vl:7b # ~6 GB; use gemma3:4b or qwen2.5vl:3b on smaller machines
pip install -r requirements.txt
python -m sorter ~/Documents/receipts -o ~/Documents/receipts_sorted
python -m sorter ./receipts --model gemma3:4b --dry-run # preview, writes nothing
Add --verify to read every document twice (second pass at a different…
₹1,234.50 and 1.234,50 are normalised, dates are converted to ISO, tax greater than total is flagged, and unknown categories are caught. Anything uncertain goes to a needs_review/ folder rather than being silently accepted. Exact duplicates are skipped by SHA-256 without spending any inference.categories.json holds your own categories and vendor rules (which always override the model), and examples.json holds corrected examples used as few-shot guidance. --model swaps in any Ollama vision model.
I generated seven fake receipts to test with: a café bill in INR, a SaaS invoice in USD, a tilted Uber photo, a German hardware-store receipt with comma decimals, an internet bill, a deliberately unreadable one, and an exact duplicate. On my first run, the model got the first five right: vendor, date, total, currency and category, including the tilted photos and the German number format. The duplicate was skipped.
The deliberately blurry receipt slipped through. The real image read 1?/09/2026 and 3?5.00, but the model confidently returned 2026-09-17 and 375.0, with no warning. For a bookkeeping tool, a quiet wrong number is worse than a flagged one.
I added two safeguards:
?, an unparseable quote, or a quote that disagrees with the extracted value gets flagged.--verify mode:
Performance: [YOUR LAPTOP: RAM, CPU/GPU] processed the 7 documents in about [X] minutes without --verify and [Y] minutes with it.
localhost (Ollama). Client invoices never leave the laptop, which is something a cloud API can't honestly promise.