# Free Freelancer Receipt Organizer Tool

A Python command-line tool (standard library only, fully offline) that
sorts receipt images and PDFs into `Year/Month` folders, renames each one
`YYYY-MM-DD-vendor-amount.ext`, and writes a CSV log (`receipt-log.csv`)
in the output folder for tax-time record keeping.

## IMPORTANT — NO OCR

This tool does **not** read text inside images or PDFs, and it makes **no
OCR claim anywhere**. The date, vendor and amount come only from the
**file name**. A file named `2026-02-05-fuel-station-3200.50.png` becomes
`2026/02/2026-02-05-fuel-station-3200.50.png`. If the file name does not
contain a usable date or vendor, the tool does not guess silently: it
flags the row `needs_review=YES` in the CSV log (see "Unclear file names"
below).

## Requirements

- Python 3.8 or newer. No extra packages to install — standard library only.
- Works on Windows, macOS and Linux. Nothing is uploaded anywhere.

## Usage

```sh
python3 receipt_organizer.py <input_folder> <output_folder>
python3 receipt_organizer.py <input_folder> <output_folder> --dry-run
python3 receipt_organizer.py <input_folder> <output_folder> --copy
python3 receipt_organizer.py <input_folder> <output_folder> --vendor-map vendors.csv
```

- By default files are **moved** into the output folder. Use `--copy` to
  keep the originals in place.
- `--dry-run` prints the plan and moves nothing — try this first.
- Accepted files: `.jpg`, `.jpeg`, `.png`, `.pdf`. Other files are skipped
  and reported, not moved.
- If two receipts would get the same new name, the second becomes
  `...-2.ext`, `...-3.ext`, and so on — nothing is overwritten.

## File-name format it understands

- Date: `2026-03-14`, `2026_03_14`, `20260314`, or day-first `14-03-2026`.
- Amount: a number at the end of the name, e.g. `-4500` or `-3200.50`,
  optionally with a currency marker (`-PKR4500`, `-Rs4500`, `-$12.50`).
- Vendor: whatever words remain between the date and the amount, e.g.
  `fuel-station`, `internet-provider`.

Examples:

| Original file name | Result |
|---|---|
| `2026-01-12-office-supplies-store-4500.jpg` | `2026/01/2026-01-12-office-supplies-store-4500.jpg` |
| `2026-02-05-fuel-station-3200.50.png` | `2026/02/2026-02-05-fuel-station-3200.50.png` |
| `20260315-courier-service-1200.jpg` | `2026/03/2026-03-15-courier-service-1200.jpg` |

## Unclear file names — manual vendor entry

If a file name has no vendor (for example `IMG_20260310.jpg`, or a bare
`scan001.pdf`), the tool files it as `unknown-vendor` and marks
`needs_review=YES` in the CSV log. Fix it one of these ways, then re-run:

1. **Rename the file first** (preferred): give it a date and a vendor,
   e.g. rename `IMG_20260310.jpg` to `2026-03-10-corner-bookshop.jpg`.
2. **Use a vendor map**: create a CSV file with a header row
   `original_filename,vendor`, one row per unclear file, and pass it with
   `--vendor-map vendors.csv`. Example:
   ```csv
   original_filename,vendor
   IMG_20260310.jpg,corner-bookshop
   ```
3. If a file name has no date at all, the tool falls back to the file's
   last-modified date and flags the row — check it and rename the file
   with the real receipt date if the fallback is wrong.

## The CSV log

`receipt-log.csv` in the output folder has one row per receipt:
`original_filename, new_filename, date, vendor, amount, currency, year,
month, destination_path, needs_review, date_source`. It is a plain record
of what was filed, not a tax return — check the figures yourself and with
your accountant before using them for any filing. This tool is not tax
advice.

## Sample files

The `samples/` folder contains five small **sample** receipt files made
for testing only — they are clearly labelled samples, not real receipts,
and contain no real purchase data. Copy (do not move) them into a test
input folder and run the tool to try it out:

```sh
mkdir -p /tmp/receipt-test-in /tmp/receipt-test-out
cp samples/* /tmp/receipt-test-in/
python3 receipt_organizer.py /tmp/receipt-test-in /tmp/receipt-test-out
```

## NOT a duplicate

This is receipt-specific: it sorts receipt images/PDFs and builds a
receipt CSV log. The generic Bulk File Organizer sorts any files with no
receipt naming or log, and the Folder Backup Zipper only archives a
folder into a zip — neither renames receipts by date-vendor-amount nor
produces a tax log.