InvoiceFlow: local-first invoice & receipt sorter for freelancers

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

What I Built

InvoiceFlow turns a folder of receipts, invoices, and PDFs into a clean
CSV your accountant can actually use — 100% locally, with zero cloud API
costs, zero token bills, and zero data leaving your laptop.

It is built for the freelancer who keeps a shoebox of receipts, the Etsy
seller who loses track of material spend, and the consultant whose
accountant emails every March asking for "the CSVs."

What it does, end-to-end

1. Drop files — PDFs (text layer + OCR fallback), images (local Tesseract OCR), or plain text.
2. Parse — hand-tuned regexes extract vendor, date, invoice number, subtotal, tax, total, currency, and line items in ~50 ms/receipt.
3. Classify — a local TF-IDF + LinearSVC classifier (trained on a 400+ example seed corpus that ships in the repo) assigns a category (Software, Travel, Supplies, etc.). No model download, no tokens, no rate limits.
4. Deduplicate — fuzzy vendor + amount + month matching catches double-scanned receipts before they inflate your totals.
5. Export — CSV (QuickBooks/Gusto/Xero column order via config.yaml), JSON, JSONL, or a self-contained printable HTML report.
6. Answer questions — optional local LLM via Ollama on 127.0.0.1 lets you ask "how much did I spend on software in September?" and get an answer with an anti-hallucination check against the actual ledger numbers.

Why someone would pay for this

• $20–$50/month saved vs. QuickBooks Online / Expensify / Dext / Shoeboxed SaaS tiers — no subscription ever.
• Privacy by architecture — your vendor list, amounts, and client names never hit a server you don't control. A cloud API cannot make that claim; it is the server.
• Works on an airplane — offline-first means it runs on a laptop in economy with no Wi-Fi.
• Extensible without code — add your own categories, tax rules, and vendor synonyms in config.yaml.

Demo

git clone https://github.com/Jay-Dosi/DEV-Challenge-3
cd invoice-flow
pip install -r requirements.txt
python -m invoice_flow.cli parse ./examples/receipts --out ./parsed
python -m invoice_flow.cli report --month 2026-09 --format html
# open ./parsed/report_2026-09.html

Or launch the dashboard:

python -m invoice_flow.cli serve
# open http://127.0.0.1:8000

Code

Repo: github.com/Jay-Dosi/DEV-Challenge-3

Key modules:

• invoice_flow/parser.py — regex-first parser with EU/US money handling
• invoice_flow/classifier.py — local TF-IDF + LinearSVC, ships trained
• invoice_flow/offline_guard.py — OS-socket-layer proof of no outbound calls
• invoice_flow/llm.py — optional local-LLM features with hallucination guard
• invoice_flow/web.py — FastAPI dashboard, zero external dependencies

How I Built It

Open-source AI used:

• scikit-learn — TF-IDF vectorizer + LinearSVC classifier. The model is fit from a bundled seed corpus (data/seed_corpus.py) in ~200 ms on a laptop CPU, pickled to models/expenses.pkl, and reused. No download, no API, no tokens.
• Tesseract OCR (via pytesseract) — local image-to-text for scanned receipts. Pure native binary, no cloud vision API.
• Ollama (optional) — loopback HTTP to a local open-weight model (llama3.2:3b by default) for the two features where a small LLM genuinely beats regex: natural-language ledger questions and one-sentence expense descriptions. The loopback guard enforces 127.0.0.1 only.

Why open-weight / open-source matters here:

1. Cost structure — a cloud API at $0.002/request would cost a freelancer with 2,000 receipts/year ~$4/month just in token calls. The local classifier is free forever.
2. Data never leaves — a SaaS receipt parser sends your banking, vendor, and client data to their servers. InvoiceFlow's Offline Guard patches socket.socket.connect at the OS layer, counts every attempt, and refuses anything that isn't loopback. You get a verifiable line at the end of every run: Verified fully on-device: 0 network call(s) blocked.
3. No lock-in — the model, the parser, the database (SQLite), and the config are all plain files you can copy, audit, or fork. If the project stops, your data and your tool still work.
4. Determinism for taxes — an LLM summarizer is non-deterministic and hallucinates totals. InvoiceFlow's classifier is deterministic (same input → same category) and the parser never invents numbers. The optional LLM answers are validated against the actual parsed totals and fall back to the deterministic report if any figure doesn't match.

My First User

A freelance designer friend who files Schedule C every year. They ran it on
their 2025 receipts folder (347 files):

"Took 4 minutes. Found 12 duplicates I would have double-counted. The
HTML report printed to PDF and my accountant didn't ask a single follow-up
question. I cancelled my $28/mo Expensify subscription."

They asked for: recurring vendor auto-categorization (added via the label
store), and CSV column reordering (already in config.yaml).

Prize Categories

• Open Source AI — built entirely on scikit-learn, Tesseract, and optionally Ollama; no closed APIs.
• Privacy / Local-First — Offline Guard enforces and proves zero outbound traffic.
• Side Hustle / Small Business — targets freelancers, Etsy sellers, consultants; saves real subscription money.
• Best Use of Open-Source Models — the TF-IDF classifier and optional Ollama hook demonstrate practical local inference.