Metadata-Version: 2.4
Name: finances
Version: 0.3.0
Summary: See where your money goes from your own bank statements and exports, checked against their printed totals. No bank login; nothing leaves your machine.
Author: roshanlam
License-Expression: MIT
Project-URL: Homepage, https://github.com/roshanlam/finances
Project-URL: Issues, https://github.com/roshanlam/finances/issues
Project-URL: Changelog, https://github.com/roshanlam/finances/blob/main/CHANGELOG.md
Keywords: personal-finance,bank-statements,pdf,reconciliation,budgeting,local-first,privacy,ofx,beancount,ledger
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Office/Business :: Financial :: Accounting
Classifier: Topic :: Office/Business :: Financial
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pdfplumber>=0.11.10
Dynamic: license-file

# finances

[![PyPI](https://img.shields.io/pypi/v/finances)](https://pypi.org/project/finances/)
[![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue)](pyproject.toml)
[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)

See where your money goes from your own bank statements and exports. No bank
login, no Plaid, no account linking, no cloud. Everything runs on your machine
and nothing is uploaded anywhere.

```bash
uvx finances demo && uvx finances web --db demo.db --open    # try it on made-up data
```

[![A 20-second tour of finances, on made-up demo data](docs/demo.gif)](docs/demo.mp4)

*20 seconds, on the made-up data from `finances demo`. Click for the full video with sound.*

The thing that makes it different: **a statement prints its own totals, so the
extraction can be proved correct.** Every figure this produces traces back to a
line on a statement, and the tool tells you when it cannot.

```
$ finances check

Store       finances.db
Rows        1180 transactions, 2025-01-03 to 2025-12-29
Statements  36

Reconciled  36/36 (100%)

Every statement reconciles and no months are missing. The totals downstream
are traceable to a statement line.
```

A tool built on a bank API cannot do this. It receives a feed of transactions
with no independent total to check them against, so a dropped charge or a
flipped sign is invisible. Here the statement is the ground truth, and
reconciliation is enforced rather than assumed.

---

# Running it

Three ways in. Pick one; they all end at the same dashboard on
`http://localhost:8787`.

## Try it first, with made-up data

Nobody should have to hand over a year of bank statements to find out whether
a tool is any good. `demo` writes twelve months of an invented checking account
and credit card — paychecks, rent, a subscription that raises its price, a
holiday spike — into a separate `demo.db`. It goes through the same
reconciliation and categorizer as a real statement.

```bash
# with uv, nothing to clone
uvx finances demo
uvx finances web --db demo.db --open

# or from a checkout
git clone https://github.com/roshanlam/finances && cd finances
uv run finances demo
uv run finances web --db demo.db --open

# or with Docker, nothing else installed
docker compose --profile demo up demo        # then open http://localhost:8787
```

## With your statements: uv

Requires [uv](https://docs.astral.sh/uv/) (it fetches Python 3.12+ if you do
not have it). For the browser dashboard you also need Node 20+; without it
everything in the terminal still works.

```bash
uv sync                                  # one dependency: pdfplumber
mkdir -p PDFs                            # drop your statement PDFs in here
uv run finances pipeline PDFs/           # parse, categorize, check, report
uv run finances web --open               # builds the dashboard on first run
```

Any folder layout works — subfolders are searched too. Tested against Amex,
Chase (card and checking), Capital One and Discover. For any other bank, use
its export (next section), or let a local model read the PDF.

## Any bank: CSV, OFX/QFX, CAMT.053, MT940

Nearly every bank lets you download your transactions. `import` reads those
files, works out the columns, the date format, the decimal separator and which
way the amounts are signed, and checks them against whatever balances the file
carries:

```bash
uv run finances import ~/Downloads/activity.csv
uv run finances import exports/                 # a whole folder, any mix of formats
```

| Format | Who exports it | How it is checked |
|---|---|---|
| CSV with a running balance | most bank accounts | every row has to move the balance by exactly its amount |
| CSV without one | most card sites | imported, and marked unverified — honestly |
| OFX / QFX / QBO | US banks ("Quicken" / "Money" download) | each export's opening balance must equal the previous export's closing balance |
| CAMT.053 | European banks (ISO 20022 XML) | opening balance + every booked entry = closing balance |
| MT940 | European banks (SWIFT) | opening balance + every entry = closing balance |

Headers are recognised in English, German, French, Spanish, Italian, Dutch and
the Nordic languages, `1.234,56` and `05.01.2026` are read the European way, and
a summary block above the header (Bank of America does this) is skipped. When
downloads overlap, rows already in the store for that account are skipped, not
counted twice. If a CSV is ambiguous, say so: `--sign out-negative`,
`--date-format %d.%m.%Y`, `--account 1234 --issuer "My Bank" --kind card`.

## A bank the parser does not know: a local model, checked

```bash
uv run finances parse PDFs/ --llm
```

When a statement's layout is not understood (nothing extracted, or the
extraction does not reconcile), its text goes to a model running **on your
machine** — Ollama, LM Studio or llama.cpp — which lists the transaction rows.
The statement's printed totals are still read by the deterministic parser, so
the model never supplies both the answer and the check: its rows are kept only
if they add up to those totals. Otherwise they are discarded and the statement
stays marked as a mismatch. `FINANCES_LLM_FALLBACK=1` turns this on for the
dashboard's uploads too.

**Always look at the `check` verdict at the end before trusting anything
else.** If it does not say 100%, the numbers downstream are built on a bad
extraction, and every other report will tell you so too.

## With your statements: Docker

```bash
mkdir -p PDFs                            # drop your statement PDFs in here
docker compose up                        # then open http://localhost:8787
```

On start the container parses whatever is in `./PDFs` (unchanged files are
skipped), categorizes it, prints the `check` verdict and serves the dashboard.
The store and every generated report land in `./data`. Every command works the
same way inside it:

```bash
docker compose run --rm finances check
docker compose run --rm finances cashflow
docker compose run --rm finances ask --example top-merchants
```

The port is published on `127.0.0.1` only, and `.dockerignore` is a whitelist:
your PDFs and database are never sent to the Docker daemon or baked into an
image.

## The dashboard

Your statements, the reconciliation verdict for each one, spending by month and
category, detected subscriptions, and a searchable transaction table. **You
can drag new statement PDFs or bank exports straight onto it**: they are read
on drop, and the reply tells you how many transactions came out and whether the
file checks out.

- **Wrapped** — your year in money: where it went, your regular, the month that
  got away from you, what subscriptions cost you all year, and how much of it
  traces back to a statement that reconciles.
- **Budgets & goals** — a monthly limit per category, projected to the end of
  the month so you hear about it before it is broken; savings goals against the
  surplus your statements actually show.
- **Cancel these** — recurring charges ranked by what dropping them saves, with
  the reason each one is there (a price that went up, three services doing one
  job). Mark one cancelled and any charge after that date is flagged.

The server makes no outbound requests, binds to localhost, and refuses any
request that does not come from a page on localhost — so another website open
in the same browser cannot read your transactions from it.

While working on the frontend, run the two halves separately —
`uv run finances web` in one terminal, `cd web && npm run dev` in another, then
use `http://localhost:5173` (it proxies `/api` through).

## Or stay in the terminal

```bash
uv run finances analyze            # where the money went
uv run finances wrapped            # your year in money
uv run finances budget             # this month against your limits
uv run finances budget cancel      # the subscriptions worth cancelling
uv run finances cashflow           # the next 60 days
uv run finances audit              # the reckoning
uv run finances cpi                # your own inflation rate
uv run finances backtest           # how accurate are the forecasts
uv run finances ask "how much did I spend on coffee in March"
```

`uv run finances` on its own lists every command; `uv run finances <command>
--help` shows that tool's own options. Inside an activated virtualenv
(`source .venv/bin/activate`), drop the `uv run`. Without uv at all:
`python3 -m venv .venv && .venv/bin/pip install -e .` and then
`.venv/bin/finances`.

## Configuration

Everything is a flag, and the few things you would otherwise repeat on every
command are also environment variables:

| Variable | Default | What it sets |
|---|---|---|
| `FINANCES_DB` | `finances.db` | the store every command reads and writes |
| `FINANCES_PDF_DIR` | `./PDFs` | where dashboard uploads are saved |
| `FINANCES_HOST` / `FINANCES_PORT` | `127.0.0.1` / `8787` | where `finances web` listens |
| `FINANCES_CURRENCY` | `USD` (or `finances fx --base`) | the currency every total is reported in |
| `FINANCES_LLM_ENDPOINT` | Ollama, LM Studio, llama.cpp on localhost | the model server for `ask`, `enrich` and `parse --llm` |
| `FINANCES_LLM_FALLBACK` | off | `1` lets a local model read unknown PDF layouts, uploads included |
| `FINANCES_PLAN` | `plan.json` | where savings goals are kept |
| `FINANCES_WEB_DIST` | `web/dist`, or the copy inside the package | a prebuilt dashboard to serve |

---

# Command reference

| Command | What it does | Writes |
|---|---|---|
| `parse PDFs/` | extract transactions from statement PDFs (`--llm` for unknown layouts) | `finances.db` |
| `import exports/` | bank CSV, OFX/QFX, CAMT.053 and MT940 files | `finances.db` |
| `check` | reconciliation and coverage report | — |
| `categorize apply` | label transactions, write back to the store | `finances.db` |
| `analyze` | spending dashboard | `finance_dashboard.html`, `insights.md` |
| `cashflow` | daily balance projection with a low-point warning | `cashflow.html` |
| `plan status` | savings goals against your real surplus | `plan.json` |
| `budget` | monthly limits per category; `budget cancel` for the cancel list | `finances.db` |
| `wrapped` | your year in money | — |
| `export beancount` | beancount, hledger/ledger, YNAB or Actual files | the file you name |
| `fx` | base currency and exchange rates | `finances.db` |
| `audit` | a strict grandfather goes through your statements | `auditor_ledger.json` |
| `cpi` | personal inflation, per merchant and per category | `cpi.html` |
| `backtest` | grades the forecasts against what actually happened | `backtest.html` |
| `ask "..."` | plain-English questions, answered offline | — |
| `anonymize` | a copy safe to share | `transactions_shareable.csv` |
| `enrich` | local-LLM merchant cleanup | `finances.db` |
| `web` | serve the browser dashboard, with PDF drag-and-drop | — |
| `demo` | a year of made-up statements, to try everything on | `demo.db` |
| `pipeline PDFs/` | parse + categorize + analyze in one run | all of the above |

Every command accepts either the SQLite store or a CSV, interchangeably:

```bash
uv run finances analyze --db finances.db
uv run finances analyze cleanedData/transactions.csv
```

## Things you will probably need

```bash
# Encrypted PDFs
uv run finances parse PDFs/ --password 1234

# A statement extracted wrong — see what the parser saw
uv run finances parse "PDFs/one bad file.pdf" --dump-columns

# Fail the build if anything does not reconcile (for a cron job)
uv run finances check --strict

# Re-parse everything, ignoring the cache
uv run finances parse PDFs/ --force

# Tell it your take-home pay, so it can work out what is left over
uv run finances analyze --income 6200

# Teach the categorizer, biggest money first
uv run finances categorize review
```

## Hand it to the tool you already use

This gets complete, checked transactions out of statements. Budgeting apps and
plain-text ledgers are better at other things, so it hands the rows over:

```bash
uv run finances export beancount -o money.beancount --balances
uv run finances export hledger   -o money.journal   --balances   # ledger-cli reads it too
uv run finances export ynab      -o exports/        # one CSV per account
uv run finances export actual    -o exports/
```

With `--balances`, every reconciled statement's closing balance becomes a
balance assertion, so `bean-check` or `hledger check` re-verifies the whole
history independently of this tool. Card payments from checking go through an
`Assets:Transfers` account, so they net to zero instead of counting twice.

## More than one currency

Each transaction keeps the currency its file was in. Totals are reported in one
base currency, at rates you set — there is no rate feed, because nothing here
goes online:

```bash
uv run finances fx --base EUR            # report in euros
uv run finances fx USD=0.92 GBP=1.17     # 1 USD is 0.92 of the base currency
uv run finances fx                       # what is set, and what is still missing
```

Rows in a currency with no rate are left out of the totals and counted, and the
dashboard says so, rather than quietly adding euros to dollars.

## Asking questions offline

`ask` needs a local model server. Without one, `--sql` and `--examples` still
work:

```bash
uv run finances ask --examples
uv run finances ask --sql "SELECT category, SUM(amount) FROM transactions GROUP BY 1 ORDER BY 2 DESC"
```

With one:

```bash
brew install ollama && ollama pull llama3.1:8b
uv run finances ask "what did I spend on delivery last month" --explain
```

Something in the 3B–8B range is plenty. Avoid reasoning models here — they take
minutes per question for no benefit on this task. Pick explicitly with
`--model llama3.1:8b`.

## If something goes wrong

| Symptom | Cause and fix |
|---|---|
| `finances.db does not exist` | Run `parse` first. |
| `check` reports mismatches | The extraction is wrong for those files. Run `finances parse <file> --dump-columns` to see the columns it found, or `--llm` to let a local model try. |
| A bank is not supported | Download its CSV/OFX export and `finances import` it, or [ask for the bank](https://github.com/roshanlam/finances/issues/new?template=new-bank.yml). |
| `check` reports gaps | A statement month is missing from your folder. Totals are being computed on incomplete data. |
| Lots of `Uncategorized` | `categorize review` to teach it, or `enrich` to use a local LLM. |
| `cashflow` will not project | It could not find a checking-account balance. Pass `--balance 2400`. |
| Amounts look wrong | Almost always a column-detection problem. `--dump-columns`, then `--amount-col last` or `second-last` to override. |

---

# How it fits together

```
PDFs ─────▶ parse.py ───┐
   (llm_parse.py, checked)  ├──▶ finances.db ──▶ engine.py ──▶ every other tool
exports ─▶ importer.py ─┘          │                 │
                                   │          the read model: what counts as
       each file checked against   │          spending, which months are complete,
       its own totals or balances  │          what repeats, what is verified
                                   └──▶ export.py ──▶ beancount, hledger, YNAB, Actual
```

```
finances/          the package — one module per tool, plus the shared core below
  cli.py           `finances <command>`: the front door, dispatches to each tool
  parse.py         PDFs -> the store, reconciling each statement as it goes
  importer.py      bank exports (CSV, OFX, CAMT.053, MT940) -> the store, balance-checked
  llm_parse.py     a local model for unknown PDF layouts, kept only if it reconciles
  engine.py        the read model every tool shares
  export.py        the store -> beancount, hledger, YNAB, Actual
  api.py           the dashboard's JSON API and static server
  demo.py          the made-up store
  ...              analyze, cashflow, cpi, backtest, ask, planner, anonymize, ...
web/               the dashboard (React + Vite), served by `finances web`
tests/             stdlib unittest, no test dependencies
docker/  Dockerfile  docker-compose.yml
```

Every module still runs on its own too: `python -m finances.parse --help`.

- **`models.py`** — one definition of a transaction and a statement. The SQLite
  schema and the CSV columns are both generated from it, so adding a field is a
  single edit and the store migrates itself.
- **`database.py`** — the store, plus a content-hash cache so re-running the
  parser skips files that have not changed.
- **`utils.py`** — money, date and merchant parsing, the debt formulas, and the
  recurring-charge detector.
- **`engine.py`** — the semantics. Everything downstream agrees about what a
  month, a surplus and a subscription are because they all ask this.

# What it does that other tools do not

**Proves its own numbers.** Extracted charges are checked against the total the
statement prints for itself, and the verdict is stored, not just displayed.
Missing statement months are detected and reported as gaps, so an average is
never quietly computed over incomplete data.

This is not decorative. Building it found a noise filter matching the month
"Apr" and discarding entire statements, sign inversions on two issuers, a
year-rollover that dated 62 transactions to the wrong December, and a primary
key that silently dropped 41 of one statement's 181 transactions. All of them
looked fine in a dashboard. None survive a reconciliation check.

**Tells you about next month, not just last month.** `cashflow` projects the
daily balance forward from known recurring charges and detected paycheck
cadence — distinguishing semi-monthly from biweekly, because biweekly gives you
three-paycheck months and that changes the answer. It reports a band rather than
a line and says plainly that it is not a confidence interval.

**Measures your inflation, not the country's.** `cpi` weights per-category price
changes by your spending and tracks per-merchant prices over time, against real
BLS Consumer Expenditure and CPI-U reference data shipped with the project.

**Grades its own forecasts.** `backtest` walks forward month by month, predicts
each month using only data from before it, and scores nine predictors against
what happened. It refuses to name a winner when the sample cannot support one.

**Makes your data shareable.** `anonymize` has four levels up to fully
synthetic, and proves what survived — per-category totals are printed side by
side so you can see which figures are still exactly true.

# Categorization

Rules, in order, first hit wins. Every answer records which rule fired and how
confident it is:

1. what you taught it (`learned_rules.json`, always wins)
2. context rules — `COSTCO`+`GAS` is fuel, `UBER`+`EATS` is delivery
3. bank phrases — a deposit account names its own transaction type
4. brand table, exact token match, never substring
5. keyword rules, word-boundary regex
6. issuer MCC labels, where the statement prints its own category
7. behaviour — cadence and amount, when the name says nothing

Scored against 159 real-shaped descriptors with processor prefixes, glued
city/state suffixes and issuer preambles:

```
$ uv run finances categorize eval
  correct         159  100.0%
  wrong             0    0.0%   <- these corrupt analysis
  left unknown      0    0.0%   <- these are honest
```

# Tests

```bash
uv run python -m unittest discover tests
```

289 tests, no test dependencies. The parser's golden-file tests skip when
`PDFs/` is empty, so a fresh clone runs the rest. The golden-file harness
records per-statement extraction totals so a parser change that moves a number
is visible:

```bash
uv run python tests/run.py --update-golden   # after a deliberate change
uv run python tests/run.py --check-golden    # exits 1 on drift
```

# Privacy

Your statements and the store never leave the machine. `PDFs/`, `*.db`, the
generated dashboards and `anonymize_map.json` are all gitignored. The map file
is what turns `MERCHANT_007` back into a real name — keep it, do not share it.

`ask`, `enrich` and `parse --llm` talk only to a model server on localhost.
Nothing else in the project makes a network request at all. See
[SECURITY.md](SECURITY.md) for how the dashboard is locked to your own machine
and how to report a problem.

# Not financial advice

Arithmetic on your own statements. The forecasts are extrapolations of your past
spending and say so, `backtest` will tell you how wrong they have been, and none
of it knows anything about your life beyond what the statements print.

# License

MIT. See [LICENSE](LICENSE).
