DEV Community: Hamid Naeem Khan

Shoebox: a receipt sorter for freelancers that never uploads a receipt

Hamid Naeem Khan — Sun, 18 Oct 2026 15:02:33 +0000

This is a submission for the Hacktoberfest Open-Source AI Challenge Week 2: Side Hustle

What I Built

Every freelancer I know has the same tax-season ritual: a Downloads folder full of Invoice_final(2).pdf, forwarded receipts, and invoices they sent to clients, and a weekend lost to sorting it. Shoebox does the sorting.

Point it at a messy folder. It reads each document with a model running on your own machine, then:

files a copy into YYYY/YYYY-MM/category/ with a readable name (2026-04-02_GitHub_4.00.pdf)
flags duplicates (the same receipt emailed twice)
sets aside anything it can't read or doesn't trust, in _needs-review/
writes a ledger.csv an accountant can open, and prints spend by category, with invoices you sent counted as income

It is a dry run by default, and it copies, never moves, because the originals are your client records.

Who would pay: a freelancer or one-person agency once a year at tax time, or a bookkeeper who wants a first pass over a client's shoebox of documents. I have not tested willingness to pay (see "My First User").

Demo

ollama pull llama3.2:3b
shoebox samples/inbox --out out            # dry run: writes out/ledger.csv only
shoebox samples/inbox --out out --apply    # copies files into out/YYYY/YYYY-MM/category/

samples/make_samples.py generates fictional receipts and invoices (PDF and text) so you can try it without touching real records.

Code

HamidKhan1001 / shoebox

Shoebox

Local-only receipt and invoice sorter for freelancers. Point it at a messy folder; it reads each document with an open-weight model running on your own machine (Ollama, default llama3.2:3b), files copies into YYYY/YYYY-MM/category/, flags duplicates, and writes a ledger.csv for your accountant. Nothing leaves your laptop: the client refuses any non-loopback host.

Use

python3.11 -m venv .venv && source .venv/bin/activate && pip install -e ".[dev]"
ollama pull llama3.2:3b
shoebox ~/Downloads/receipts --out ~/books         # dry run, writes ledger only
shoebox ~/Downloads/receipts --out ~/books --apply # copies files (originals untouched)
pytest

Supports text-based PDFs and txt/md/csv/eml/html. Scanned images need OCR, which is not included.

Trust checks

Small models make mistakes, so every result is validated: the extracted total must appear in the document text, dates must be plausible, and anything failing goes to _needs-review/ instead of being filed silently.

Sample data and eval

…

View on GitHub

How I Built It

Model: llama3.2:3b, an open-weight model, served locally by Ollama. Ollama's JSON-schema format option constrains the output to my fields, so I always get parseable JSON.
Extraction: pypdf for text-based PDFs, plain reads for txt/eml/html. No OCR, so scanned images are listed as unreadable rather than guessed at.
Validation (the part that matters): a small model will sometimes invent numbers, so every result is checked against the source text. The extracted total must literally appear in the document, the date must be plausible, and a failure sends the file to _needs-review/ instead of filing it. "Invoice you sent" is forced to category income in code, not left to the model.
Privacy by construction: the client refuses any host that isn't loopback, so a misconfigured URL fails instead of leaking.

How well does it work? I generated 15 fictional documents with known answers and scored llama3.2:3b (CPU only, an Intel Mac, about 25-28 s per document):

field	first prompt	fixed prompt
date	15/15	15/15
total	15/15	15/15
vendor	13/15	12/15
doc type	12/15	12/15
category	3/15	12/15

The first run was bad: category was 3/15 because my own prompt mentioned "income" and the 3B model labelled nearly everything income. Removing it from the model's choices took category to 12/15.

What is still wrong: three supplier invoices were read as invoices I sent, two client invoices got my own name as the vendor, and one vendor came back empty. Of the 6 documents with an error, only 1 was flagged for review; the other 5 would be filed silently. My validator catches hallucinated amounts and bad dates, but not a wrong category or the wrong party. So the honest status is: reliable on amounts and dates, shaky on judgment, and you should skim the ledger before trusting it for taxes. This is 15 synthetic documents and a single run, so treat it as indicative, not a benchmark.

Why Does Open Innovation Matter?

Receipts and client invoices are exactly what you don't want to paste into someone else's API: client names, rates, addresses. Running an open-weight model locally means the documents never leave the laptop, there is no per-page fee eating a small business's margin, and it works on a train with no signal. I can also swap the model with --model as better small models appear, and a niche like "invoices from my country's utilities" is something I could fine-tune for, which a closed API wouldn't let me do. The tradeoff is real, though: a 3B model on a CPU is slower and less accurate than a frontier API, and I'd say so to any customer.

My Agent Session

I built this with Claude Code.

My First User

Prize Categories

TrailBird: an offline bird-call identifier for your next hike

Hamid Naeem Khan — Sun, 11 Oct 2026 18:58:40 +0000

This is a submission for the Hacktoberfest Open-Source AI Challenge Week 1: Touch Grass

What I Built

TrailBird is a local bird-call identifier for hikers. You give it a short recording, and it returns the top 3 likely species with confidence scores. It flags low-confidence results as uncertain and shows a short listening note. The screen is meant for a quick glance, so the walk stays the main event. Audio never leaves your laptop. It's for hikers and casual birders who want to put the phone down and look up.

Demo

A live demo isn't deployed yet. The repo is public, and I'm finishing the model wiring and UI now. I'll add a demo video and link to this post when it's ready.

Code

HamidKhan1001 / trailbird

Offline bird-call identifier (BirdNET, Gradio) for the Hacktoberfest Touch Grass challenge

TrailBird: offline bird-call identifier

Identify a bird from a short recording on the trail, with no internet and no audio leaving your laptop.

Status: work in progress (Hacktoberfest 2026, "Touch Grass" challenge). Done so far: audio loading/resampling/chunking (trailbird/audio.py) and top-3 / uncertainty / disclaimer formatting (trailbird/results.py). Still to do: BirdNET inference wiring, Gradio UI, tests, demo audio.

Planned model

BirdNET via the birdnet Python package (~6,000 species), run locally with ONNX.

Code: MIT. Model weights: CC BY-NC-SA 4.0 (non-commercial, share-alike, attribution required). Fine for this non-commercial project; not OSI-open weights.

Disclaimer

Results are an assistive prediction, not a definitive identification.

License

Project code: MIT. BirdNET model weights: CC BY-NC-SA 4.0.

View on GitHub

Current state: audio loading, resampling and chunking, plus top-3 ranking, uncertainty flagging and the disclaimer, are in the repo. BirdNET inference, the Gradio UI and tests are still in progress.

How I Built It

Model: BirdNET, an open-weight model covering about 6,000 species, run locally through the birdnet Python package with ONNX.
Audio pipeline (Python): mono conversion, resampling to 48 kHz, and 3-second chunking.
Result handling: the top-3 results are marked uncertain when the best score is under 50% or within 10 points of second place. Every result carries an "assistive prediction, not a definitive identification" disclaimer.
UI: Gradio, planned.
Licenses: the code is MIT. The BirdNET weights are CC BY-NC-SA 4.0, so non-commercial use with attribution and share-alike. BirdNET is by the Cornell Lab of Ornithology and Chemnitz University of Technology.

Why Does Open Innovation Matter?

Open weights let identification run on a laptop with no signal, no API key and no upload of where you were or what you recorded. A closed API needs connectivity, which trails often lack, and sends your recordings to someone else's server. Open code and weights also mean anyone can audit, fix or extend it, for example with regional species notes.

My Agent Session

Built with Claude Code. [Add your DevRelay session embed here, or delete this section.]

HI

Hamid Naeem Khan — Sun, 11 Oct 2026 17:37:40 +0000