TallyMatch

The problem

Manually checking receipts against a bank or card statement is tedious and error-prone, and that is exactly where real mistakes hide. A missing receipt, a duplicate charge, or a subscription that renewed twice can be easy to overlook in a long list of transactions. TallyMatch is for freelancers and small business owners doing their own bookkeeping, not accountants managing many clients. TallyMatch runs entirely in memory, with no login, no database, and no saved history — upload, check, done.

Why not just paste this into a chat AI?

The exact-match logic runs first in code, the same way every time. GPT-5.6 is called only for the leftover cases that a rule cannot resolve, rather than redoing the whole matching job from scratch. That makes the simple, repeatable checks transparent while reserving AI judgment for ambiguity.

How this was built

Built with Codex over four days, the project started as a simple exact-match version with no AI at all and was verified working first. GPT-5.6 Luna, using the explicit model ID gpt-5.6-luna, was then added specifically for ambiguous cases. Codex explained each change as it was made, and each step was verified against real test data before moving to the next one, rather than building everything at once and checking it all at the end.

A real example

A $25 bank charge can be matched to a $20 receipt as a likely tip, while a duplicate charge can be correctly identified as a duplicate rather than a missing receipt.

What it does

1. Accepts two CSV uploads.
2. Matches a bank transaction to an unused receipt when the absolute amounts agree (within one cent) and their dates are within three days.
3. Sends every remaining bank transaction and receipt together in one OpenAI request using gpt-5.6-luna, along with a list of already-matched pairs as background context, so it can compare the whole group and recognize likely duplicate charges.
4. Uses that review to identify likely tips, fees, partial refunds, duplicate charges, and genuinely unexplained items, with one plain-English reason per item.
5. Shows matched pairs and review items in one table.

If no API key is available, exact matching still works and the app tells you that AI review was skipped.

Run from an empty folder

1. Install Python 3.10 or newer.

2. Open a terminal in this project folder.

3. Create and activate a virtual environment (recommended):

   Windows PowerShell

   python -m venv .venv
   .\.venv\Scripts\Activate.ps1

   macOS / Linux

   python3 -m venv .venv
   source .venv/bin/activate

   If PowerShell blocks the activation script with a message about running scripts being disabled on the system, skip activation. Use the venv-direct commands shown in steps 4 and 5 instead; they use the same isolated environment without needing to change any system settings.

4. Install the app's dependency:

   If activation worked:

   pip install -r requirements.txt

   If activation was blocked:

   .venv\Scripts\python.exe -m pip install -r requirements.txt

   macOS / Linux (after activation):

   pip install -r requirements.txt

5. Start the app:

   If activation worked:

   python app.py

   If activation was blocked:

   .venv\Scripts\python.exe app.py

   macOS / Linux (after activation):

   python app.py

6. Visit http://127.0.0.1:5000 in your browser.

CSV formats

Bank/card statement:

date,description,amount
2026-07-01,SQ *JOE123,-4.50
2026-07-02,BOOKSTORE,18.00

Receipts:

date,vendor,amount
2026-07-01,Joe's Coffee,4.50
2026-07-02,Bookstore,18.00

Dates can be YYYY-MM-DD, DD/MM/YYYY, or MM/DD/YYYY. Bank charges may be negative; receipt amounts may be positive.

Ready-to-use sample files are included in sample_data/fake_bank_statement.csv and sample_data/fake_receipts.csv, so you can try the app immediately without creating your own test data.

API key safety

Copy .env.example to .env and place OPENAI_API_KEY=... there. The app loads it automatically. The real .env is ignored by Git. The page also has an optional request-only key field; a pasted key takes precedence over .env, is never written to disk, and is discarded as soon as the request ends.

Requests are routed through AICredits, an OpenAI-compatible billing gateway, to work around Indian card restrictions on OpenAI's direct billing — the model requested is still gpt-5.6-luna. This is controlled by the optional OPENAI_BASE_URL variable; without it, the app talks to OpenAI directly.

Known limitations

• Cash transactions are explicitly out of scope.
• AI suggestions are review aids, not accounting decisions; confirm tips, fees, refunds, and duplicates before acting on them.
• Receipts are entered as CSV rows in this version. Real-world receipts are typically individual photos or PDF pages — direct image or PDF upload with automatic extraction is a natural next step, not yet built.