Bill Bench

Clean and reconcile CSV/XLSX bills, with a source row behind every retained amount.

For people reviewing inconsistent bill exports: normalise merchants, separate exact duplicates and send uncertain rows to a review queue before exporting a five-sheet workbook. A merchant you classified once does not need another model call or another manual category decision for each monthly export.

Try the live demo · Open the sample workbook · Inspect its ledger

The bundled sample is synthetic: 125 input rows = 114 retained + 3 exact duplicates + 8 unparseable, and every value links back to its source sheet and row.

Quick start

Use the browser demo with no account or key, or run the offline Python CLI (Python 3.9+, standard library only). This cleans the included January example with a reviewed rules file and checks the result:

git clone https://github.com/NickkkLian/bill-categoriser.git
cd bill-categoriser
python3 -B demo.py clean examples/january.csv --rules examples/rules.json --out output-january --verify

To clean your own exports, run python3 -B demo.py clean bills.csv another-export.xlsx --out output-clean --verify. This writes the output and runs the existing checker with the same threshold in one command; verification failure returns a nonzero exit status. Keep the original files unchanged for verification. The rules support CAD and explicit dates; unknown merchants require review. The default workflow processes files locally; selecting your own model provider sends a suggestion request to that provider.

Try it

In the browser — open the live demo, or serve the local folder with python3 -m http.server -d docs and open http://localhost:8000. The page starts with the 125 generated sample rows or restores your saved workbook. Workbook tools provides Import, Bills, Needs review, Duplicates, Rules, Change log, Dashboard and Export. Import accepts a dropped .xlsx or .csv file and parses it locally. The site assets and fonts are self-hosted.

From the command line — no packages, accounts or network access are needed.

python3 -B demo.py build
python3 -B demo.py check

build writes output/dirty-input.xlsx, output/ledger.json and output/cleaned-bills.xlsx; check verifies them (the delivered files are already built, so you can open the workbook first). On Windows use python if that is your Python command.

clean <files...> reads your exports in argument order and writes ledger.json and the same five-sheet cleaned-bills.xlsx, with monthly totals for the months present in your retained bills. It defaults to output-clean/ in your current directory. By default it uses the existing exact merchant rules: a merchant outside the alias map stays Uncategorised for review. Add --rules rules.json to reuse aliases and the threshold exported from the browser. It makes no model calls. Use --high-cad on both clean and check to change the review threshold. check re-reads the original input paths recorded in the ledger, checks every output cell/formula and rebuilds twice; keep those files available and unchanged. Absolute source paths are recorded for traceability, including when two files share a name. The output cannot overwrite an input or the generated demo folder.

Seed 42 result	Rows	Known amount (CAD)
Retained in Bills	114	131,711.27
Exact duplicates excluded	3	6,256.65
Unable to parse completely	8	5,884.89
All input rows	125	143,852.81

Four input amounts are unknown; they are kept out of the arithmetic, never treated as zero. 131,711.27 + 6,256.65 + 5,884.89 = 143,852.81 is asserted by check, by the browser's own checks card, and by the workbook's reconciliation formula.

Reuse reviewed rules next month

In the browser's Rules & thresholds view, choose Export rules JSON after applying your reviewed aliases. clean --rules FILE accepts that exact aliases / high_cad schema, so a merchant you classified once does not need another model call or another manual category decision for each monthly export. Matching remains exact after the same normalisation used by the browser.

Try the included synthetic two-month example:

python3 -B demo.py clean examples/january.csv --rules examples/rules.json --out output-january --verify
python3 -B demo.py clean examples/february.csv --rules examples/rules.json --out output-february --verify
python3 -B demo.py check --out output-february --rules examples/rules.json

The rules file sets the threshold, so there is no second --high-cad to remember. Categories are Supplies, Utilities, Software, Rent, Transport and Uncategorised. New merchants without an exact rule still require review.

The ledger stores a rules snapshot. Later check --out output-february uses that snapshot and can reproduce the result even if the original rules file moved; check --rules FILE additionally checks that the policy you supplied matches the snapshot.

What the browser version adds

This is the beginning of the README. Read the rest at the original. Read the full README ↗