statementproof 0.1.0__tar.gz

statementproof-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Carthorne
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

statementproof-0.1.0/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.4
+Name: statementproof
+Version: 0.1.0
+Summary: Extract transactions from bank statement PDFs -- and prove the extraction is right, or say it isn't.
+License: MIT
+Keywords: bank-statement,pdf,csv,bookkeeping,accounting,reconciliation,extraction,converter,quickbooks,xero
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Topic :: Office/Business :: Financial :: Accounting
+Classifier: Topic :: Text Processing :: Filters
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pdfplumber>=0.10
+Provides-Extra: dev
+Requires-Dist: reportlab>=4.0; extra == "dev"
+Dynamic: license-file
+
+# statementproof
+
+Bank statement PDF → CSV extraction that **tells you when it got it wrong.**
+
+Most converters hand you output with no way to know if it is correct. A bank
+statement is one of the few documents carrying its own checksum — the balances.
+
+## What it does differently
+
+**1. Geometry, not regex.** The most-cited converter failure is *"columns shift,
+debit and credit values land in the wrong places."* That happens because
+`extract_text()` flattens a 2-D layout and discards x-position — the only signal that
+distinguishes a debit column from a credit column. This reads word coordinates and
+clusters money columns by their right edges.
+
+**2. Column roles from arithmetic, not headers.** Which column is the running balance
+is decided by behaviour, not by header text — header text differs across banks and is
+often missing on continuation pages.
+
+**3. Sign from the balance chain.** If the balance went down, it was a debit,
+regardless of whether a minus glyph survived extraction.
+
+**4. It refuses to bluff.** With nothing to check against, output is `UNVERIFIED` —
+never a silent pass.
+
+## Verdicts
+
+| verdict | meaning |
+|---|---|
+| `VERIFIED` | transactions reproduce the statement's own balances |
+| `FAILED` | they do not — **with the offending row named** |
+| `UNVERIFIED` | statement carries no balances to check against |
+
+## What it CANNOT catch — read this
+
+The check is **arithmetic consistency**, not correctness. It cannot see errors that do
+not disturb the arithmetic:
+
+- junk rows with a `0.00` amount (page headers picked up as transactions)
+- wrong dates
+- garbled or truncated descriptions
+- two errors that cancel out
+
+**"Provably arithmetically consistent" is the honest claim. "Provably correct" is not,
+and is not made here.**
+
+## Free test mode — try it on your own statement
+
+```bash
+python -m statementproof YOUR_STATEMENT.pdf              # validate, print a report
+python -m statementproof YOUR_STATEMENT.pdf --csv out.csv
+python -m statementproof YOUR_STATEMENT.pdf --diagnostic # shareable layout report
+```
+
+**It runs entirely on your machine. Nothing is uploaded, nothing is stored, no file is
+written unless you name one with `--csv`.**
+
+That is not a policy, it is a property of the code, and it is tested:
+`tests/test_privacy.py` parses every module's AST and **fails the build if any
+networking library is imported anywhere in the package.**
+
+### The `--diagnostic` flag, and why it exists
+
+The single thing that would most improve this tool is a library of real statement
+*layouts*. A layout can be described without describing anyone's money, so
+`--diagnostic` prints exactly that: column positions, column density, date-token
+**shapes** (`DD/DD`, not `10/02`), and where extraction broke.
+
+It contains **no amounts, no balances, no descriptions, no dates, no account numbers,
+no names, and not even the filename.** It prints to your screen so you can read the
+whole thing before deciding whether to share it. The tool never sends it anywhere —
+there is no code that could.
+
+Those exclusions are asserted by tests against a known statement, not just intended.
+
+## Status
+
+Early, and scoped to **text-layer PDFs only** — statements downloaded from a bank
+portal. Scans and photographs are not supported; the tool detects them and says so
+rather than producing garbage.
+
+**7/7 layouts extracted exactly, 0 false assurances.** Six are synthetic; the seventh
+is reproduced from a real bank's published specimen and is the useful one — it found
+three bugs the synthetic set never could, including `MM/DD` dates with no year, which
+alone produced **0/21 extracted** while the synthetic suite still reported 6/6.
+
+⚠️ **Passing a test suite written by the author of the code under test is worth very
+little.** Six invented layouts passed while a real bank's date format extracted
+nothing. **No real customer file has been processed yet** — which is what the free
+test mode above is for.
+
+    python statementproof/tests/make_statements.py     # build synthetic corpus
+    python statementproof/tests/make_real_derived.py   # build real-bank-derived layout
+    python statementproof/tests/score.py               # score extraction
+    python statementproof/tests/test_failure_modes.py  # validator behaviour
+    python statementproof/tests/test_privacy.py        # privacy promises

statementproof-0.1.0/README.md

@@ -0,0 +1,50 @@
+# CARTHORNE — AUTOPILOT
+**State of the business in 20 lines. Read this first.**
+
+**Day 2 · 2026-08-20**
+
+| | |
+|---|---|
+| Capital | **$100 — untouched.** Hard ceiling, nothing more coming. |
+| Burn | **$59.40/mo** → **$89.11/mo on 2026-08-31** (11 days) |
+| **Runway** | **51 days now · 34 days after Aug 31** |
+| Revenue | **$0** |
+| Break-even | **$89/mo** = 5 sales/mo of a $19 one-off |
+| Thesis | **NONE. This is the problem.** |
+
+## THE MACHINE WORKS. THERE IS NO BUSINESS IN IT.
+
+**Built and verified:** security audit · metric definitions locked before data · spend tracker
+reading real token counts · Telegram live (verified by traffic, not a config flag) · Stripe live ·
+billing understood · asset inventory · 27 commits · DK queue at **0 blocking**.
+
+**Not built:** a thesis, a product, an audience, a customer, a dollar.
+
+## THE MAP SO FAR — where NOT to look
+
+| buyer | verdict | why |
+|---|---|---|
+| SMB owners | ❌ | need a sales call — QR's $0 proves it |
+| Developers | ❌ | build it themselves, give it away free |
+| Enterprise | ❌ | won't trust a solo shop; escrow + self-host demands |
+| Regulated / financial | ❌ | §11 |
+| **Individual non-developers** | **← all that remains** | |
+
+**Candidate 1 (agent cost forensics): KILLED.** Demand real — a $6,000 overnight bill, Uber's
+budget gone in 4 months. But six free tools exist including Anthropic's own. *Pain × free
+alternatives = no business.*
+
+## THE HONEST RISK
+
+**Two days in, the ratio of infrastructure-and-self-examination to revenue-seeking is roughly
+20:1.** Four ADRs, three ops docs, two corrections of my own errors — and one round of demand
+research. Some of that was forced (Telegram was genuinely dead, the burn figure genuinely wrong),
+but §12's warning about building machinery instead of a business is **currently the live risk,
+not a hypothetical one.**
+
+## NEXT
+
+Round 3 demand research: individual non-developers, supply-side checked **first**. Reddit and
+Stack Overflow are blocked to our crawler — browser access is the unexplored path.
+
+**Decision point: a candidate by 2026-08-27, or cut scope.**

statementproof-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "statementproof"
+version = "0.1.0"
+description = "Extract transactions from bank statement PDFs -- and prove the extraction is right, or say it isn't."
+readme = "statementproof/README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+keywords = [
+    "bank-statement", "pdf", "csv", "bookkeeping", "accounting",
+    "reconciliation", "extraction", "converter", "quickbooks", "xero",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Financial and Insurance Industry",
+    "Topic :: Office/Business :: Financial :: Accounting",
+    "Topic :: Text Processing :: Filters",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "pdfplumber>=0.10",
+]
+
+[project.optional-dependencies]
+dev = ["reportlab>=4.0"]
+
+[project.scripts]
+statementproof = "statementproof.cli:main"
+
+[tool.setuptools]
+packages = ["statementproof"]
+
+[tool.setuptools.package-data]
+statementproof = ["README.md"]

statementproof-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

statementproof-0.1.0/statementproof/README.md

@@ -0,0 +1,96 @@
+# statementproof
+
+Bank statement PDF → CSV extraction that **tells you when it got it wrong.**
+
+Most converters hand you output with no way to know if it is correct. A bank
+statement is one of the few documents carrying its own checksum — the balances.
+
+## What it does differently
+
+**1. Geometry, not regex.** The most-cited converter failure is *"columns shift,
+debit and credit values land in the wrong places."* That happens because
+`extract_text()` flattens a 2-D layout and discards x-position — the only signal that
+distinguishes a debit column from a credit column. This reads word coordinates and
+clusters money columns by their right edges.
+
+**2. Column roles from arithmetic, not headers.** Which column is the running balance
+is decided by behaviour, not by header text — header text differs across banks and is
+often missing on continuation pages.
+
+**3. Sign from the balance chain.** If the balance went down, it was a debit,
+regardless of whether a minus glyph survived extraction.
+
+**4. It refuses to bluff.** With nothing to check against, output is `UNVERIFIED` —
+never a silent pass.
+
+## Verdicts
+
+| verdict | meaning |
+|---|---|
+| `VERIFIED` | transactions reproduce the statement's own balances |
+| `FAILED` | they do not — **with the offending row named** |
+| `UNVERIFIED` | statement carries no balances to check against |
+
+## What it CANNOT catch — read this
+
+The check is **arithmetic consistency**, not correctness. It cannot see errors that do
+not disturb the arithmetic:
+
+- junk rows with a `0.00` amount (page headers picked up as transactions)
+- wrong dates
+- garbled or truncated descriptions
+- two errors that cancel out
+
+**"Provably arithmetically consistent" is the honest claim. "Provably correct" is not,
+and is not made here.**
+
+## Free test mode — try it on your own statement
+
+```bash
+python -m statementproof YOUR_STATEMENT.pdf              # validate, print a report
+python -m statementproof YOUR_STATEMENT.pdf --csv out.csv
+python -m statementproof YOUR_STATEMENT.pdf --diagnostic # shareable layout report
+```
+
+**It runs entirely on your machine. Nothing is uploaded, nothing is stored, no file is
+written unless you name one with `--csv`.**
+
+That is not a policy, it is a property of the code, and it is tested:
+`tests/test_privacy.py` parses every module's AST and **fails the build if any
+networking library is imported anywhere in the package.**
+
+### The `--diagnostic` flag, and why it exists
+
+The single thing that would most improve this tool is a library of real statement
+*layouts*. A layout can be described without describing anyone's money, so
+`--diagnostic` prints exactly that: column positions, column density, date-token
+**shapes** (`DD/DD`, not `10/02`), and where extraction broke.
+
+It contains **no amounts, no balances, no descriptions, no dates, no account numbers,
+no names, and not even the filename.** It prints to your screen so you can read the
+whole thing before deciding whether to share it. The tool never sends it anywhere —
+there is no code that could.
+
+Those exclusions are asserted by tests against a known statement, not just intended.
+
+## Status
+
+Early, and scoped to **text-layer PDFs only** — statements downloaded from a bank
+portal. Scans and photographs are not supported; the tool detects them and says so
+rather than producing garbage.
+
+**7/7 layouts extracted exactly, 0 false assurances.** Six are synthetic; the seventh
+is reproduced from a real bank's published specimen and is the useful one — it found
+three bugs the synthetic set never could, including `MM/DD` dates with no year, which
+alone produced **0/21 extracted** while the synthetic suite still reported 6/6.
+
+⚠️ **Passing a test suite written by the author of the code under test is worth very
+little.** Six invented layouts passed while a real bank's date format extracted
+nothing. **No real customer file has been processed yet** — which is what the free
+test mode above is for.
+
+    python statementproof/tests/make_statements.py     # build synthetic corpus
+    python statementproof/tests/make_real_derived.py   # build real-bank-derived layout
+    python statementproof/tests/score.py               # score extraction
+    python statementproof/tests/test_failure_modes.py  # validator behaviour
+    python statementproof/tests/test_privacy.py        # privacy promises

statementproof-0.1.0/statementproof/__init__.py

@@ -0,0 +1,2 @@
+"""statementproof - verifiable bank statement extraction."""
+__version__ = "0.1.0"

statementproof-0.1.0/statementproof/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+import sys
+sys.exit(main())

statementproof-0.1.0/statementproof/cli.py

@@ -0,0 +1,188 @@
+"""statementproof CLI -- validate a bank statement PDF locally.
+
+Design constraint that shapes everything here: **nothing leaves this machine.**
+
+This tool is asking people to point it at a bank statement. That document carries
+their name, address, account number, employer, and every place they spent money last
+month. "Nothing stored" cannot be a marketing line; it has to be a structural fact.
+So:
+
+  - there is no network code in this package at all
+  - no file is written unless the user names one (--csv)
+  - the diagnostic (--diagnostic) is opt-in and contains NO financial content:
+    no amounts, no descriptions, no dates, no account numbers, no names -- only
+    layout geometry. It is printed to the screen so it can be read in full before
+    anyone chooses to share it.
+
+The diagnostic exists because a corpus of real statement LAYOUTS is the thing that
+makes this parser better, and layouts can be described without describing anyone's
+money.
+
+Usage:
+    python -m statementproof STATEMENT.pdf
+    python -m statementproof STATEMENT.pdf --csv transactions.csv
+    python -m statementproof STATEMENT.pdf --diagnostic
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+import sys
+
+from .extract import parse, find_balances, is_money, is_date_start, rows_from_page
+from .validate import validate, fmt
+
+BANNER = r"""
+  statementproof  --  bank statement extraction that tells you when it is wrong
+  runs entirely on this machine | no network | nothing uploaded
+"""
+
+
+def build_diagnostic(pdf_path, txns, diag, opening, closing, res):
+    """A shareable description of the LAYOUT, containing no financial data.
+
+    Deliberately excluded: amounts, balances, descriptions, dates, names, account
+    numbers, and the file name. Included: how many columns were found and where,
+    which date format matched, and where extraction broke. Nothing here identifies
+    a person or reveals a transaction.
+    """
+    import pdfplumber
+
+    date_shapes = set()
+    col_count_hist = {}
+    with pdfplumber.open(pdf_path) as pdf:
+        pages = len(pdf.pages)
+        for page in pdf.pages:
+            for r in rows_from_page(page):
+                toks = r.tokens
+                n = is_date_start(toks)
+                if n:
+                    # Record the SHAPE of the date, not the date.
+                    t0 = toks[0]
+                    shape = "".join("D" if ch.isdigit() else
+                                    ("A" if ch.isalpha() else ch) for ch in t0)
+                    date_shapes.add(shape)
+                k = sum(1 for w in r.words if is_money(w["text"]))
+                col_count_hist[k] = col_count_hist.get(k, 0) + 1
+
+    return {
+        "statementproof_version": __import__("statementproof").__version__,
+        "pdf": {
+            "pages": pages,
+            "has_text_layer": diag.get("rows", 0) > 0,
+            "text_rows_detected": diag.get("rows"),
+        },
+        "layout": {
+            "money_columns_found": len(diag.get("columns") or []),
+            "money_column_x_positions": diag.get("columns"),
+            "column_density": diag.get("density"),
+            "balance_column_index": diag.get("balance_col"),
+            "single_column_resolution": diag.get("single_column_resolved"),
+            "date_token_shapes": sorted(date_shapes),
+            "money_tokens_per_row_histogram":
+                {str(k): v for k, v in sorted(col_count_hist.items())},
+        },
+        "outcome": {
+            "transactions_extracted": len(txns),
+            "rows_skipped": len(diag.get("skipped") or []),
+            "skip_reasons": sorted({s["why"] for s in (diag.get("skipped") or [])}),
+            "opening_balance_found": opening is not None,
+            "closing_balance_found": closing is not None,
+            "verdict": res.verdict,
+            "checks_run": res.checks_run,
+            "problem_kinds": sorted({p.kind for p in res.problems}),
+        },
+        "contains_no_financial_data": True,
+    }
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(
+        prog="statementproof",
+        description="Validate bank statement PDF extraction. Runs locally; uploads nothing.")
+    ap.add_argument("pdf", help="path to a bank statement PDF")
+    ap.add_argument("--csv", metavar="OUT", help="write extracted transactions to CSV")
+    ap.add_argument("--diagnostic", action="store_true",
+                    help="print a shareable layout report containing no financial data")
+    ap.add_argument("--quiet", action="store_true", help="verdict line only")
+    args = ap.parse_args(argv)
+
+    if not os.path.isfile(args.pdf):
+        print("error: no such file: %s" % args.pdf, file=sys.stderr)
+        return 2
+
+    if not args.quiet:
+        print(BANNER)
+
+    try:
+        opening, closing = find_balances(args.pdf)
+        txns, diag = parse(args.pdf, balance_hints=(opening, closing))
+    except Exception as e:
+        print("error: could not read PDF (%s: %s)" % (type(e).__name__, e), file=sys.stderr)
+        return 2
+
+    res = validate(txns, opening, closing)
+
+    if args.quiet:
+        print(res.verdict)
+    else:
+        if diag.get("rows", 0) == 0:
+            print("  This PDF has no text layer -- it is a scan or a set of images.")
+            print("  statementproof reads text-layer PDFs only. A statement downloaded")
+            print("  directly from your bank's website normally has one; a scanned or")
+            print("  photographed page does not. OCR support is not built yet.\n")
+
+        print("  opening balance : %s" % (fmt(opening) if opening is not None else "not found"))
+        print("  closing balance : %s" % (fmt(closing) if closing is not None else "not found"))
+        print("  transactions    : %d extracted, %d row(s) skipped"
+              % (len(txns), len(diag.get("skipped") or [])))
+        print()
+        print("  " + res.report().replace("\n", "\n  "))
+        print()
+
+        if res.verdict == "VERIFIED":
+            print("  The extracted transactions reproduce this statement's own balances.")
+            print("  That means the arithmetic is consistent. It does NOT mean every")
+            print("  description or date is correct -- errors that do not change the")
+            print("  totals cannot be detected this way.")
+        elif res.verdict == "FAILED":
+            print("  The extraction does NOT reconcile. The row(s) named above are where")
+            print("  the running balance stops following. Do not import this without")
+            print("  checking them against the PDF.")
+        elif diag.get("rows", 0) == 0:
+            print("  Nothing could be read from this file, so there is nothing to check.")
+            print("  This is the scan case described above, not a problem with the")
+            print("  statement itself.")
+        else:
+            print("  This statement does not carry enough balance information to check")
+            print("  the extraction against. The output may be correct -- but nothing")
+            print("  here proves it, so it is not claimed.")
+
+    if args.csv:
+        import csv as _csv
+        with open(args.csv, "w", newline="", encoding="utf-8") as f:
+            w = _csv.writer(f)
+            w.writerow(["row", "date", "description", "amount", "balance", "verdict"])
+            for t in txns:
+                w.writerow([t.row, t.date, t.description, fmt(t.amount_cents),
+                            fmt(t.balance_cents) if t.balance_cents is not None else "",
+                            res.verdict])
+        if not args.quiet:
+            print("\n  wrote %d rows to %s" % (len(txns), args.csv))
+
+    if args.diagnostic:
+        d = build_diagnostic(args.pdf, txns, diag, opening, closing, res)
+        print("\n" + "=" * 68)
+        print("  LAYOUT DIAGNOSTIC -- contains no amounts, names, dates or account numbers.")
+        print("  Read it below. Share it only if you choose to; nothing is sent by this tool.")
+        print("=" * 68)
+        print(json.dumps(d, indent=2))
+
+    return 0 if res.verdict == "VERIFIED" else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

statementproof-0.1.0/statementproof/extract.py

@@ -0,0 +1,314 @@
+"""PDF bank statement -> candidate transactions, using word geometry.
+
+Why geometry instead of regex on extracted text:
+
+The most-cited failure of generic converters is "columns shift, debit and credit
+values land in the wrong places." That happens because `page.extract_text()` flattens
+a 2-D layout into 1-D lines and throws away the only reliable signal a statement has
+-- the x-position of each number. A debit column and a credit column are not
+distinguishable by their digits; they are distinguishable by where they sit.
+
+So this module never regexes a flattened line. It:
+
+  1. pulls words with (x0, x1, top) from pdfplumber
+  2. groups words into rows by vertical position
+  3. clusters the x-positions of every numeric token across the whole document to
+     discover where the money columns actually are
+  4. assigns each number to a column by position, then labels the columns by
+     behaviour (the column that changes monotonically with the others is the
+     running balance)
+
+Step 4 is the part that matters: column ROLES are inferred from arithmetic, not from
+header text, because header text is inconsistent across banks and often absent on
+continuation pages.
+"""
+
+from __future__ import annotations
+
+import re
+import statistics
+from dataclasses import dataclass
+
+from .validate import Txn, to_cents
+
+# A money token: 1,234.56 / 1234.56 / (1,234.56) / 1234.56- / -1234.56 / .26
+# The bare-decimal form (".26", no leading zero) is not hypothetical: the Impact Bank
+# specimen statement prints its interest credit as ".26" on the transaction page and
+# "0.26" on the detail page -- the same figure, two renderings, in one document.
+# A synthetic corpus never produces that. Real documents do.
+MONEY_RE = re.compile(
+    r"^\(?-?[$£€]?\d{1,3}(?:,\d{3})*(?:\.\d{2})?-?\)?$"     # 1,234.56 / 1234
+    r"|^\(?-?[$£€]?\d+\.\d{2}-?\)?$"                        # 1234.56
+    r"|^\(?-?[$£€]?\.\d{2}-?\)?$"                            # .26  <- leading zero omitted
+)
+# Dates in the formats banks actually print.
+DATE_RES = [
+    re.compile(r"^\d{1,2}[/-]\d{1,2}[/-]\d{2,4}$"),   # 01/08/2026
+    re.compile(r"^\d{4}-\d{2}-\d{2}$"),               # 2026-08-01
+    # MM/DD with NO year. Extremely common on US statements -- the Impact Bank
+    # specimen prints every transaction date this way. The invented corpus always
+    # wrote full dates, so this gap survived 6/6 "passing" layouts undetected.
+    re.compile(r"^\d{1,2}[/-]\d{1,2}$"),
+    re.compile(r"^\d{1,2}$"),  # day-only, seen in statements that print the month once
+]
+MONTHS = {m.lower() for m in
+          ("Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec January February March "
+           "April May June July August September October November December").split()}
+
+
+def is_money(tok: str) -> bool:
+    t = tok.strip()
+    return bool(t) and bool(MONEY_RE.match(t)) and any(c.isdigit() for c in t)
+
+
+def is_date_start(tokens: list[str]) -> int:
+    """Return how many leading tokens form a date, or 0."""
+    if not tokens:
+        return 0
+    t0 = tokens[0].strip().rstrip(",")
+    for r in DATE_RES[:3]:
+        if r.match(t0):
+            return 1
+    # "01 Aug 2026" / "1 August"
+    if t0.isdigit() and len(tokens) > 1 and tokens[1].strip().rstrip(",.").lower() in MONTHS:
+        return 3 if len(tokens) > 2 and tokens[2].strip().isdigit() else 2
+    # "Aug 01 2026"
+    if t0.lower().rstrip(".") in MONTHS and len(tokens) > 1 and tokens[1].strip().isdigit():
+        return 3 if len(tokens) > 2 and tokens[2].strip().isdigit() else 2
+    return 0
+
+
+@dataclass
+class Row:
+    top: float
+    words: list[dict]
+
+    @property
+    def tokens(self) -> list[str]:
+        return [w["text"] for w in self.words]
+
+    @property
+    def text(self) -> str:
+        return " ".join(self.tokens)
+
+
+def rows_from_page(page, y_tol: float = 2.5) -> list[Row]:
+    """Group words into visual rows by their vertical position."""
+    words = page.extract_words(use_text_flow=False, keep_blank_chars=False)
+    if not words:
+        return []
+    words.sort(key=lambda w: (round(w["top"], 1), w["x0"]))
+    rows: list[Row] = []
+    for w in words:
+        if rows and abs(w["top"] - rows[-1].top) <= y_tol:
+            rows[-1].words.append(w)
+        else:
+            rows.append(Row(top=w["top"], words=[w]))
+    for r in rows:
+        r.words.sort(key=lambda w: w["x0"])
+    return rows
+
+
+def money_columns(rows: list[Row], tol: float = 12.0) -> list[float]:
+    """Cluster the right-edges of numeric tokens to find money column positions.
+
+    Right edge, not left: money is right-aligned in every statement layout, so x1
+    is stable across values of different magnitude while x0 is not.
+    """
+    edges = [w["x1"] for r in rows for w in r.words if is_money(w["text"])]
+    if not edges:
+        return []
+    edges.sort()
+    clusters: list[list[float]] = [[edges[0]]]
+    for e in edges[1:]:
+        if e - clusters[-1][-1] <= tol:
+            clusters[-1].append(e)
+        else:
+            clusters.append([e])
+    # Keep columns that occur often enough to be real columns, not stray figures.
+    threshold = max(2, len(rows) // 20)
+    return [statistics.median(c) for c in clusters if len(c) >= threshold]
+
+
+def assign_columns(row: Row, cols: list[float], tol: float = 14.0):
+    """Map each money token in the row to its column index."""
+    out: dict[int, str] = {}
+    for w in row.words:
+        if not is_money(w["text"]):
+            continue
+        best, bestd = None, tol
+        for i, c in enumerate(cols):
+            d = abs(w["x1"] - c)
+            if d < bestd:
+                best, bestd = i, d
+        if best is not None:
+            out[best] = w["text"]
+    return out
+
+
+def parse(pdf_path: str, balance_hints: tuple[int | None, int | None] | None = None
+          ) -> tuple[list[Txn], dict]:
+    """Extract transactions. Returns (txns, diagnostics).
+
+    `balance_hints` is (opening_cents, closing_cents) when known. It is used only to
+    disambiguate single-money-column statements, where position alone cannot say
+    whether that column holds amounts or running balances.
+
+    Deliberately conservative: a row that cannot be confidently parsed is recorded
+    in diagnostics['skipped'] rather than guessed at. A wrong row that validates is
+    far more damaging than a missing row that shows up as a balance break.
+    """
+    import pdfplumber
+
+    diag = {"pages": 0, "rows": 0, "skipped": [], "columns": [], "balance_col": None}
+    all_rows: list[Row] = []
+    with pdfplumber.open(pdf_path) as pdf:
+        diag["pages"] = len(pdf.pages)
+        for page in pdf.pages:
+            all_rows.extend(rows_from_page(page))
+
+    diag["rows"] = len(all_rows)
+    cols = money_columns(all_rows)
+    diag["columns"] = [round(c, 1) for c in cols]
+    if not cols:
+        return [], diag
+
+    # Candidate transaction rows: start with a date and carry at least one number.
+    cands: list[tuple[Row, int, dict[int, str]]] = []
+    for r in all_rows:
+        n = is_date_start(r.tokens)
+        if not n:
+            continue
+        assigned = assign_columns(r, cols)
+        if assigned:
+            cands.append((r, n, assigned))
+
+    if not cands:
+        return [], diag
+
+    # Identify the running-balance column: the rightmost column present on nearly
+    # every transaction row. Amount columns are sparse (a row is either a debit or
+    # a credit); the balance column is dense.
+    density = {i: sum(1 for _, _, a in cands if i in a) / len(cands)
+               for i in range(len(cols))}
+    dense = [i for i, d in density.items() if d >= 0.9]
+    bal_col = max(dense) if dense else None
+
+    # Single-column statements are genuinely ambiguous: one dense money column is
+    # either "amount, no balance printed" or "balance, no amount printed", and
+    # position cannot tell them apart. Resolve it the same way this module resolves
+    # everything else -- by arithmetic. Test both readings against the statement's
+    # own opening/closing figures and keep whichever reconciles.
+    if len(cols) == 1 and bal_col == 0:
+        vals = []
+        for _, _, a in cands:
+            try:
+                vals.append(to_cents(a[0]))
+            except (ValueError, TypeError):
+                vals.append(None)
+        clean = [v for v in vals if v is not None]
+        op, cl = balance_hints if balance_hints else (None, None)
+        as_amounts = (op is not None and cl is not None
+                      and op + sum(clean) == cl)
+        as_balances = bool(clean) and cl is not None and clean[-1] == cl
+        if as_amounts and not as_balances:
+            bal_col = None                     # the column is amounts
+            diag["single_column_resolved"] = "amounts (reconciles to closing)"
+        elif as_balances and not as_amounts:
+            diag["single_column_resolved"] = "balances (last value == closing)"
+        elif as_amounts and as_balances:
+            diag["single_column_resolved"] = "ambiguous - both readings reconcile"
+        else:
+            # Neither reconciles. Prefer amounts: a wrong balance silently poisons
+            # the chain check, whereas wrong amounts get caught by the aggregate.
+            bal_col = None
+            diag["single_column_resolved"] = "neither reconciles - assumed amounts"
+
+    diag["balance_col"] = bal_col
+    diag["density"] = {i: round(d, 2) for i, d in density.items()}
+
+    txns: list[Txn] = []
+    for idx, (r, ndate, assigned) in enumerate(cands, start=1):
+        toks = r.tokens
+        date = " ".join(toks[:ndate])
+        money_texts = {v for v in assigned.values()}
+        desc = " ".join(t for t in toks[ndate:] if t not in money_texts).strip()
+
+        bal = None
+        if bal_col is not None and bal_col in assigned:
+            try:
+                bal = to_cents(assigned[bal_col])
+            except (ValueError, TypeError):
+                bal = None
+
+        amt_cols = [i for i in assigned if i != bal_col]
+        amount = None
+        if len(amt_cols) == 1:
+            try:
+                amount = to_cents(assigned[amt_cols[0]])
+            except (ValueError, TypeError):
+                amount = None
+        elif len(amt_cols) > 1:
+            # Separate debit and credit columns: leftmost of the two is
+            # conventionally the debit. Sign is resolved below by the balance
+            # chain where possible, so do not guess here.
+            try:
+                vals = {i: to_cents(assigned[i]) for i in sorted(amt_cols)}
+                amount = vals[sorted(amt_cols)[0]]
+            except (ValueError, TypeError):
+                amount = None
+
+        if amount is None:
+            diag["skipped"].append({"row": idx, "text": r.text[:90],
+                                    "why": "no unambiguous amount column"})
+            continue
+
+        txns.append(Txn(row=idx, date=date, description=desc,
+                        amount_cents=amount, balance_cents=bal,
+                        source_line=r.text[:200]))
+
+    # Resolve sign from the balance chain: if bal[i] < bal[i-1] the amount is a
+    # debit regardless of how it was printed. This is the geometry payoff -- sign
+    # comes from arithmetic, not from a minus glyph that may not survive extraction.
+    if bal_col is not None:
+        opening_hint = balance_hints[0] if balance_hints else None
+        for i, t in enumerate(txns):
+            if t.balance_cents is None:
+                continue
+            # Seed row 0 from the opening balance. Without it the FIRST transaction
+            # has no predecessor, its sign cannot be derived from the chain, and a
+            # debit printed without a minus stays positive -- which is exactly the
+            # single error the Impact Bank layout produced (row 1, +4.23 vs -4.23).
+            prev = txns[i - 1].balance_cents if i > 0 else opening_hint
+            if prev is None:
+                continue
+            delta = t.balance_cents - prev
+            if delta != 0 and abs(abs(delta) - abs(t.amount_cents)) <= 1:
+                t.amount_cents = delta
+
+    return txns, diag
+
+
+def find_balances(pdf_path: str) -> tuple[int | None, int | None]:
+    """Locate opening and closing balances from summary lines."""
+    import pdfplumber
+
+    opening = closing = None
+    open_pat = re.compile(r"(opening|previous|beginning|brought forward|balance b/f)", re.I)
+    close_pat = re.compile(r"(closing|ending|new balance|balance c/f|carried forward)", re.I)
+    with pdfplumber.open(pdf_path) as pdf:
+        for page in pdf.pages:
+            for r in rows_from_page(page):
+                text = r.text
+                monies = [w["text"] for w in r.words if is_money(w["text"])]
+                if not monies:
+                    continue
+                try:
+                    val = to_cents(monies[-1])
+                except (ValueError, TypeError):
+                    continue
+                if opening is None and open_pat.search(text):
+                    opening = val
+                if close_pat.search(text):
+                    closing = val
+    return opening, closing

statementproof-0.1.0/statementproof/validate.py

@@ -0,0 +1,202 @@
+"""Balance validation for extracted bank statement transactions.
+
+The point of this module: most PDF-to-CSV converters give you output with no way to
+know whether it is correct. A bank statement is one of the few documents that carries
+its own checksum -- the balances. If the extracted rows do not reproduce the closing
+balance from the opening balance, at least one row is wrong, and it can usually be
+located exactly.
+
+Two independent checks:
+
+  1. AGGREGATE   opening + sum(amounts) == closing
+  2. CHAIN       for every row with a running balance: bal[i] == bal[i-1] + amount[i]
+
+The chain check is the useful one. Aggregate tells you *that* something is wrong;
+chain tells you *which row*, which is what makes the failure actionable rather than
+just discouraging.
+
+Money is handled in integer minor units (cents) throughout. Floats are not used for
+comparison anywhere -- 0.1 + 0.2 != 0.3 is not an acceptable source of false alarms
+in an accounting tool.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from decimal import Decimal, InvalidOperation
+from typing import Iterable, Sequence
+
+
+def to_cents(value) -> int:
+    """Convert a money value to integer cents. Never uses float arithmetic."""
+    if isinstance(value, int):
+        return value * 100
+    if isinstance(value, Decimal):
+        return int((value * 100).to_integral_value(rounding="ROUND_HALF_UP"))
+    if isinstance(value, float):
+        # Round-trip through str so 12.34 does not become 12.339999999999999.
+        return int((Decimal(str(value)) * 100).to_integral_value(rounding="ROUND_HALF_UP"))
+    if isinstance(value, str):
+        s = value.strip()
+        if not s:
+            raise ValueError("empty money value")
+        neg = False
+        # Accounting negatives: (1,234.56) means -1234.56
+        if s.startswith("(") and s.endswith(")"):
+            neg, s = True, s[1:-1]
+        # Trailing sign: 1,234.56- (common in some bank exports)
+        if s.endswith("-"):
+            neg, s = True, s[:-1]
+        for ch in "$£€,  ":
+            s = s.replace(ch, "")
+        if s.startswith("-"):
+            neg, s = True, s[1:]
+        if not s:
+            raise ValueError("no digits in money value %r" % value)
+        try:
+            cents = int((Decimal(s) * 100).to_integral_value(rounding="ROUND_HALF_UP"))
+        except InvalidOperation as exc:
+            raise ValueError("unparseable money value %r" % value) from exc
+        return -cents if neg else cents
+    raise TypeError("unsupported money type: %r" % type(value))
+
+
+def fmt(cents: int) -> str:
+    """Render integer cents as a signed decimal string."""
+    sign = "-" if cents < 0 else ""
+    c = abs(cents)
+    return "%s%d.%02d" % (sign, c // 100, c % 100)
+
+
+@dataclass
+class Txn:
+    """One extracted transaction. `balance` is the running balance if the statement
+    prints one; None when the format does not carry it."""
+    row: int
+    date: str
+    description: str
+    amount_cents: int
+    balance_cents: int | None = None
+    source_line: str = ""
+
+
+@dataclass
+class Problem:
+    kind: str          # "chain_break" | "aggregate_mismatch" | "no_evidence"
+    row: int | None
+    message: str
+    expected_cents: int | None = None
+    found_cents: int | None = None
+
+
+@dataclass
+class Result:
+    ok: bool
+    checks_run: list[str] = field(default_factory=list)
+    problems: list[Problem] = field(default_factory=list)
+    txn_count: int = 0
+    computed_closing_cents: int | None = None
+
+    @property
+    def verdict(self) -> str:
+        if self.ok:
+            return "VERIFIED"
+        if any(p.kind == "no_evidence" for p in self.problems):
+            return "UNVERIFIED"
+        return "FAILED"
+
+    def report(self) -> str:
+        lines = ["%s  (%d transactions, checks: %s)"
+                 % (self.verdict, self.txn_count,
+                    ", ".join(self.checks_run) or "none")]
+        for p in self.problems:
+            where = "row %d" % p.row if p.row is not None else "statement"
+            lines.append("  [%s] %s: %s" % (p.kind, where, p.message))
+        return "\n".join(lines)
+
+
+def validate(
+    txns: Sequence[Txn],
+    opening_cents: int | None,
+    closing_cents: int | None,
+) -> Result:
+    """Validate extracted transactions against the statement's own balances.
+
+    Returns VERIFIED only when at least one check actually ran and passed. Absence
+    of evidence is reported as UNVERIFIED, never as success -- a converter that
+    says "looks fine" because it had nothing to check is the exact failure this
+    tool exists to prevent.
+    """
+    res = Result(ok=False, txn_count=len(txns))
+
+    if not txns:
+        res.problems.append(Problem("no_evidence", None, "no transactions extracted"))
+        return res
+
+    # --- CHAIN CHECK -------------------------------------------------------
+    # Locates the specific row that breaks the running balance.
+    with_balance = [t for t in txns if t.balance_cents is not None]
+    if len(with_balance) >= 2:
+        res.checks_run.append("chain")
+        prev = None
+        # Seed from the opening balance when we have it, so a broken FIRST row
+        # is still caught rather than silently becoming the baseline.
+        if opening_cents is not None and txns[0].balance_cents is not None:
+            prev = opening_cents
+            seq = txns
+        else:
+            prev = with_balance[0].balance_cents
+            seq = with_balance[1:]
+        for t in seq:
+            if t.balance_cents is None:
+                # Gap in the balance column: chain cannot span it. Reset and continue.
+                prev = None
+                continue
+            if prev is None:
+                prev = t.balance_cents
+                continue
+            expected = prev + t.amount_cents
+            if expected != t.balance_cents:
+                res.problems.append(Problem(
+                    kind="chain_break",
+                    row=t.row,
+                    message=("running balance does not follow: %s %+s should give %s, "
+                             "statement shows %s (off by %s)"
+                             % (fmt(prev), fmt(t.amount_cents), fmt(expected),
+                                fmt(t.balance_cents),
+                                fmt(t.balance_cents - expected))),
+                    expected_cents=expected,
+                    found_cents=t.balance_cents,
+                ))
+            # Trust the statement's own figure going forward so one bad row
+            # produces one error rather than cascading through every later row.
+            prev = t.balance_cents
+
+    # --- AGGREGATE CHECK ---------------------------------------------------
+    total = sum(t.amount_cents for t in txns)
+    if opening_cents is not None and closing_cents is not None:
+        res.checks_run.append("aggregate")
+        computed = opening_cents + total
+        res.computed_closing_cents = computed
+        if computed != closing_cents:
+            res.problems.append(Problem(
+                kind="aggregate_mismatch",
+                row=None,
+                message=("opening %s plus %d transactions totalling %s gives %s, "
+                         "but statement closing balance is %s (off by %s)"
+                         % (fmt(opening_cents), len(txns), fmt(total),
+                            fmt(computed), fmt(closing_cents),
+                            fmt(closing_cents - computed))),
+                expected_cents=closing_cents,
+                found_cents=computed,
+            ))
+
+    if not res.checks_run:
+        res.problems.append(Problem(
+            "no_evidence", None,
+            "statement carries neither a running balance column nor both "
+            "opening and closing balances -- extraction cannot be verified"))
+        return res
+
+    res.ok = not res.problems
+    return res

statementproof-0.1.0/statementproof.egg-info/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.4
+Name: statementproof
+Version: 0.1.0
+Summary: Extract transactions from bank statement PDFs -- and prove the extraction is right, or say it isn't.
+License: MIT
+Keywords: bank-statement,pdf,csv,bookkeeping,accounting,reconciliation,extraction,converter,quickbooks,xero
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Topic :: Office/Business :: Financial :: Accounting
+Classifier: Topic :: Text Processing :: Filters
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pdfplumber>=0.10
+Provides-Extra: dev
+Requires-Dist: reportlab>=4.0; extra == "dev"
+Dynamic: license-file
+
+# statementproof
+
+Bank statement PDF → CSV extraction that **tells you when it got it wrong.**
+
+Most converters hand you output with no way to know if it is correct. A bank
+statement is one of the few documents carrying its own checksum — the balances.
+
+## What it does differently
+
+**1. Geometry, not regex.** The most-cited converter failure is *"columns shift,
+debit and credit values land in the wrong places."* That happens because
+`extract_text()` flattens a 2-D layout and discards x-position — the only signal that
+distinguishes a debit column from a credit column. This reads word coordinates and
+clusters money columns by their right edges.
+
+**2. Column roles from arithmetic, not headers.** Which column is the running balance
+is decided by behaviour, not by header text — header text differs across banks and is
+often missing on continuation pages.
+
+**3. Sign from the balance chain.** If the balance went down, it was a debit,
+regardless of whether a minus glyph survived extraction.
+
+**4. It refuses to bluff.** With nothing to check against, output is `UNVERIFIED` —
+never a silent pass.
+
+## Verdicts
+
+| verdict | meaning |
+|---|---|
+| `VERIFIED` | transactions reproduce the statement's own balances |
+| `FAILED` | they do not — **with the offending row named** |
+| `UNVERIFIED` | statement carries no balances to check against |
+
+## What it CANNOT catch — read this
+
+The check is **arithmetic consistency**, not correctness. It cannot see errors that do
+not disturb the arithmetic:
+
+- junk rows with a `0.00` amount (page headers picked up as transactions)
+- wrong dates
+- garbled or truncated descriptions
+- two errors that cancel out
+
+**"Provably arithmetically consistent" is the honest claim. "Provably correct" is not,
+and is not made here.**
+
+## Free test mode — try it on your own statement
+
+```bash
+python -m statementproof YOUR_STATEMENT.pdf              # validate, print a report
+python -m statementproof YOUR_STATEMENT.pdf --csv out.csv
+python -m statementproof YOUR_STATEMENT.pdf --diagnostic # shareable layout report
+```
+
+**It runs entirely on your machine. Nothing is uploaded, nothing is stored, no file is
+written unless you name one with `--csv`.**
+
+That is not a policy, it is a property of the code, and it is tested:
+`tests/test_privacy.py` parses every module's AST and **fails the build if any
+networking library is imported anywhere in the package.**
+
+### The `--diagnostic` flag, and why it exists
+
+The single thing that would most improve this tool is a library of real statement
+*layouts*. A layout can be described without describing anyone's money, so
+`--diagnostic` prints exactly that: column positions, column density, date-token
+**shapes** (`DD/DD`, not `10/02`), and where extraction broke.
+
+It contains **no amounts, no balances, no descriptions, no dates, no account numbers,
+no names, and not even the filename.** It prints to your screen so you can read the
+whole thing before deciding whether to share it. The tool never sends it anywhere —
+there is no code that could.
+
+Those exclusions are asserted by tests against a known statement, not just intended.
+
+## Status
+
+Early, and scoped to **text-layer PDFs only** — statements downloaded from a bank
+portal. Scans and photographs are not supported; the tool detects them and says so
+rather than producing garbage.
+
+**7/7 layouts extracted exactly, 0 false assurances.** Six are synthetic; the seventh
+is reproduced from a real bank's published specimen and is the useful one — it found
+three bugs the synthetic set never could, including `MM/DD` dates with no year, which
+alone produced **0/21 extracted** while the synthetic suite still reported 6/6.
+
+⚠️ **Passing a test suite written by the author of the code under test is worth very
+little.** Six invented layouts passed while a real bank's date format extracted
+nothing. **No real customer file has been processed yet** — which is what the free
+test mode above is for.
+
+    python statementproof/tests/make_statements.py     # build synthetic corpus
+    python statementproof/tests/make_real_derived.py   # build real-bank-derived layout
+    python statementproof/tests/score.py               # score extraction
+    python statementproof/tests/test_failure_modes.py  # validator behaviour
+    python statementproof/tests/test_privacy.py        # privacy promises

statementproof-0.1.0/statementproof.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+LICENSE
+README.md
+pyproject.toml
+statementproof/README.md
+statementproof/__init__.py
+statementproof/__main__.py
+statementproof/cli.py
+statementproof/extract.py
+statementproof/validate.py
+statementproof.egg-info/PKG-INFO
+statementproof.egg-info/SOURCES.txt
+statementproof.egg-info/dependency_links.txt
+statementproof.egg-info/entry_points.txt
+statementproof.egg-info/requires.txt
+statementproof.egg-info/top_level.txt

statementproof-0.1.0/statementproof.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

statementproof-0.1.0/statementproof.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+statementproof = statementproof.cli:main

statementproof-0.1.0/statementproof.egg-info/requires.txt

@@ -0,0 +1,4 @@
+pdfplumber>=0.10
+
+[dev]
+reportlab>=4.0

statementproof-0.1.0/statementproof.egg-info/top_level.txt

@@ -0,0 +1 @@
+statementproof