keptwise 1.2.1__py3-none-any.whl

keptwise/__main__.py

@@ -0,0 +1,3 @@
+from .cli import app
+
+app(prog_name="keptwise")

keptwise/categories.py

@@ -0,0 +1,60 @@
+"""Merging and regrouping categories."""
+
+from __future__ import annotations
+
+import sqlite3
+
+
+def category_id(conn: sqlite3.Connection, name: str) -> int | None:
+    row = conn.execute("SELECT id FROM categories WHERE name = ?", (name,)).fetchone()
+    return row[0] if row else None
+
+
+def merge(conn: sqlite3.Connection, source_id: int, target_id: int) -> int:
+    """Move everything from one category into another, then delete the source.
+
+    Transactions (including ones you categorised by hand) and rules all move across.
+    Returns how many transactions moved. Doesn't commit.
+    """
+    if source_id == target_id:
+        return 0
+    moved = conn.execute(
+        "UPDATE transactions SET category_id = ? WHERE category_id = ?", (target_id, source_id)
+    ).rowcount
+    conn.execute("UPDATE rules SET category_id = ? WHERE category_id = ?", (target_id, source_id))
+    conn.execute("DELETE FROM categories WHERE id = ?", (source_id,))
+    return moved
+
+
+def merge_by_name(conn: sqlite3.Connection, sources: list[str], target: str) -> None:
+    """Merge ``sources`` into ``target``, creating ``target`` by renaming the first
+    source that exists. Missing names are skipped, so it's safe to run twice."""
+    present = [(n, category_id(conn, n)) for n in sources]
+    present = [(n, cid) for n, cid in present if cid is not None]
+    target_id = category_id(conn, target)
+    if target_id is None:
+        if not present:
+            return
+        name, target_id = present.pop(0)
+        conn.execute("UPDATE categories SET name = ? WHERE id = ?", (target, target_id))
+    for _, cid in present:
+        if cid != target_id:
+            merge(conn, cid, target_id)
+
+
+# October 2026: fewer ad hoc categories.
+SIMPLER_CATEGORIES: list[tuple[list[str], str]] = [
+    (["Eating & drinking out", "Coffee & snacks"], "Eating & drinking"),
+    (["Transport", "Car & charging"], "Transport"),
+    (["Shopping", "Health & beauty"], "Shopping"),
+    (["Going out & events", "Trips & stays"], "Going out & trips"),
+    (["Other bills & fees", "Charity"], "Other"),
+]
+
+
+def simplify(conn: sqlite3.Connection) -> None:
+    """Database migration 3: merge the starter ad hoc categories into fewer groups
+    and treat cash-machine withdrawals as Cash."""
+    for sources, target in SIMPLER_CATEGORIES:
+        merge_by_name(conn, sources, target)
+    conn.execute("UPDATE categories SET bucket = 'cash' WHERE name = 'Cash machine'")

keptwise/cli.py

@@ -0,0 +1,251 @@
+"""Command line: ``keptwise --help``."""
+
+from __future__ import annotations
+
+import contextlib
+import threading
+import time
+import urllib.request
+import webbrowser
+from pathlib import Path
+
+import click
+from click.core import ParameterSource
+
+from . import db as storage
+from . import reports
+from .importer import ImportProblem, import_path
+from .money import fmt
+from .rules import categorise
+from .seed import seed
+
+DEFAULT_PORT = 8765  # 5000 clashes with AirPlay Receiver on macOS
+
+
+def _connect(db_path: str | None, *, backup: bool = False):
+    if backup:
+        storage.backup(db_path)
+    conn = storage.connect(db_path)
+    seed(conn)
+    return conn
+
+
+@click.group(context_settings={"help_option_names": ["-h", "--help"]})
+@click.option(
+    "--db",
+    "db_path",
+    envvar=["KEPTWISE_DB", "BOOKKEEPING_DB"],
+    type=click.Path(dir_okay=False),
+    help="Database file (default: data/keptwise.db in a source checkout, else your data folder).",
+)
+@click.pass_context
+def app(ctx: click.Context, db_path: str | None) -> None:
+    """Import bank statements, track spending and plan monthly investments."""
+    ctx.obj = {"db": db_path}
+
+
+@app.command()
+@click.option("--port", default=DEFAULT_PORT, show_default=True)
+@click.option("--host", default="127.0.0.1", show_default=True)
+@click.option("--no-browser", is_flag=True, help="Don't open a browser tab.")
+@click.option(
+    "--idle-timeout",
+    default=0,
+    show_default=True,
+    metavar="MINUTES",
+    help="Stop by itself after this long without use (0 = keep running).",
+)
+@click.option("--debug", is_flag=True, help="Auto-reload on code changes.")
+@click.pass_context
+def serve(
+    ctx: click.Context, port: int, host: str, no_browser: bool, idle_timeout: int, debug: bool
+) -> None:
+    """Start the app and open it in your browser."""
+    url = f"http://{host}:{port}/"
+    if is_running(url):
+        click.echo(f"Keptwise is already running at {url}")
+        if not no_browser:
+            webbrowser.open(url)
+        return
+
+    from .web import create_app
+
+    flask_app = create_app(ctx.obj["db"])
+    if not no_browser:
+        threading.Timer(1.0, lambda: webbrowser.open(url)).start()
+    if debug:
+        click.secho(f"Keptwise is running at {url}  (Ctrl+C to stop)", fg="green")
+        flask_app.run(host=host, port=port, debug=True, use_reloader=True)
+        return
+
+    import logging
+
+    from werkzeug.serving import make_server
+
+    logging.getLogger("werkzeug").setLevel(logging.WARNING)  # no per-request log lines
+    server = make_server(host, port, flask_app, threaded=True)
+    last_used = [time.monotonic()]
+
+    @flask_app.before_request
+    def _touch() -> None:
+        last_used[0] = time.monotonic()
+
+    def stop() -> None:
+        threading.Thread(target=server.shutdown, daemon=True).start()
+
+    flask_app.config["SHUTDOWN"] = stop
+    if idle_timeout > 0:
+
+        def watch() -> None:
+            while True:
+                time.sleep(15)
+                if time.monotonic() - last_used[0] > idle_timeout * 60:
+                    server.shutdown()
+                    return
+
+        threading.Thread(target=watch, daemon=True).start()
+
+    stops = f", stops after {idle_timeout} min unused" if idle_timeout else ""
+    click.secho(f"Keptwise is running at {url}  (Ctrl+C to stop{stops})", fg="green")
+    with contextlib.suppress(KeyboardInterrupt):
+        server.serve_forever()
+    click.echo("Keptwise stopped.")
+
+
+def is_running(url: str) -> bool:
+    try:
+        with urllib.request.urlopen(url + "healthz", timeout=1) as response:
+            return response.read() == b"ok"
+    except OSError:
+        return False
+
+
+@app.command()
+@click.option("--port", default=DEFAULT_PORT, show_default=True)
+def stop(port: int) -> None:
+    """Stop an app started in the background."""
+    request = urllib.request.Request(f"http://127.0.0.1:{port}/shutdown", method="POST")
+    try:
+        urllib.request.urlopen(request, timeout=2).close()
+    except OSError:
+        click.echo("Keptwise isn't running.")
+        return
+    click.echo("Keptwise stopped.")
+
+
+@app.command("import")
+@click.argument("files", nargs=-1, required=True, type=click.Path(exists=True, dir_okay=False))
+@click.pass_context
+def import_command(ctx: click.Context, files: tuple[str, ...]) -> None:
+    """Import one or more bank CSV statements."""
+    conn = _connect(ctx.obj["db"], backup=True)
+    failed = False
+    for path in files:
+        try:
+            result = import_path(conn, path)
+        except ImportProblem as exc:
+            click.secho(f"{Path(path).name}: {exc}", fg="red", err=True)
+            failed = True
+            continue
+        click.echo(result.summary)
+    uncategorised = conn.execute(
+        "SELECT COUNT(*) FROM transactions WHERE category_id IS NULL"
+    ).fetchone()[0]
+    if uncategorised:
+        noun = "transaction has" if uncategorised == 1 else "transactions have"
+        click.secho(f"{uncategorised} {noun} no category yet.", fg="yellow")
+    if failed:
+        raise SystemExit(1)
+
+
+@app.command()
+@click.argument("month", required=False)
+@click.pass_context
+def summary(ctx: click.Context, month: str | None) -> None:
+    """Show a month's summary and investment plan (default: latest month)."""
+    conn = _connect(ctx.obj["db"])
+    months = reports.months(conn)
+    if not months:
+        raise click.ClickException("Nothing imported yet. Try: keptwise import FILE.csv")
+    month = month or months[-1]
+    if month not in months:
+        raise click.ClickException(f"No transactions for {month}. Months: {', '.join(months)}")
+    s = reports.summarise(conn, month)
+    click.secho(s.label, bold=True)
+    for key in ("regular", "cash", "adhoc", "investment"):
+        b = s.buckets[key]
+        click.echo(
+            f"  {b.label:<12} in {fmt(b.money_in):>11}   out {fmt(b.money_out):>11}"
+            f"   net {fmt(b.net):>11}"
+        )
+    click.echo(f"  {'Kept':<12} {fmt(s.surplus):>51}")
+    if s.surplus > 0:
+        plan = ", ".join(f"{fmt(a.amount)} into {a.name}" for a in s.allocations if a.share)
+        click.secho(f"In {s.next_label}: put {plan}.", fg="green")
+    else:
+        click.secho(f"Over by {fmt(-s.surplus)}: nothing to invest in {s.next_label}.", fg="red")
+    from .insights import month_flags
+
+    flags = month_flags(conn, month)
+    if flags:
+        click.echo("\nWorth a look:")
+        for flag in flags:
+            click.echo(f"  • {flag.message}")
+    if s.uncategorised_count:
+        n = s.uncategorised_count
+        click.secho(
+            f"{n} transaction{'s' if n != 1 else ''} need{'s' if n == 1 else ''} a category.",
+            fg="yellow",
+        )
+
+
+@app.command()
+@click.pass_context
+def recategorise(ctx: click.Context) -> None:
+    """Re-apply rules to every transaction you haven't categorised by hand."""
+    conn = _connect(ctx.obj["db"])
+    with conn:
+        changed = categorise(conn)
+    click.echo(f"{changed} transactions changed category.")
+
+
+@app.command()
+@click.option("--months", default=12, show_default=True, help="How many months to make up.")
+@click.option("--port", default=DEFAULT_PORT + 1, show_default=True)
+@click.option("--no-serve", is_flag=True, help="Only create the demo database.")
+@click.option("--no-browser", is_flag=True, help="Don't open a browser tab.")
+@click.pass_context
+def demo(ctx: click.Context, months: int, port: int, no_serve: bool, no_browser: bool) -> None:
+    """Try the app with a made-up year of data (kept apart from your own).
+
+    Stop it with ``keptwise stop --port 8766``.
+    """
+    from . import demo as demo_data
+
+    # Only an explicit --db is honoured here: KEPTWISE_DB points at your real data.
+    explicit = ctx.parent.get_parameter_source("db_path") == ParameterSource.COMMANDLINE
+    if explicit:
+        path = Path(ctx.obj["db"])
+    else:
+        path = storage.default_db_path().parent / "demo.db"
+        for old in (path, path.with_name(path.name + "-journal")):
+            old.unlink(missing_ok=True)  # always start the demo afresh
+    conn = _connect(str(path))
+    try:
+        added = demo_data.build(conn, months=months)
+    except ValueError as exc:
+        raise click.ClickException(f"{path} already has transactions. {exc}") from exc
+    finally:
+        conn.close()
+    click.echo(f"Made up {added} transactions over {months} months in {path}")
+    if not no_serve:
+        ctx.obj["db"] = str(path)
+        ctx.invoke(serve, port=port, no_browser=no_browser)
+
+
+def main() -> None:  # pragma: no cover
+    app()
+
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

keptwise/dates.py

@@ -0,0 +1,11 @@
+"""Date formatting that works the same on every operating system."""
+
+from __future__ import annotations
+
+from datetime import date
+
+
+def strftime(value: date, fmt: str) -> str:
+    """Like ``value.strftime(fmt)``, but ``%-d`` (day without a leading zero) also works
+    on Windows, whose C library doesn't support the ``-`` flag."""
+    return value.strftime(fmt.replace("%-d", str(value.day)))

keptwise/db.py

@@ -0,0 +1,212 @@
+"""SQLite storage with versioned schema migrations (``PRAGMA user_version``)."""
+
+from __future__ import annotations
+
+import os
+import sqlite3
+import sys
+from collections.abc import Iterator
+from contextlib import contextmanager
+from datetime import datetime
+from pathlib import Path
+
+BUCKETS: dict[str, str] = {
+    "regular": "Regulars",
+    "cash": "Cash",
+    "investment": "Investments",
+    "adhoc": "Ad hoc",
+}
+
+PROJECT_ROOT = Path(__file__).resolve().parents[2]
+
+
+def default_db_path() -> Path:
+    """Where the database lives.
+
+    1. ``$KEPTWISE_DB`` (or the older ``$BOOKKEEPING_DB``) if set.
+    2. ``data/keptwise.db`` inside the project, when running from a source checkout.
+       A ``data/bookkeeping.db`` from before the rename is used if it exists.
+    3. Otherwise the usual per-user data folder for the operating system.
+    """
+    env = os.environ.get("KEPTWISE_DB") or os.environ.get("BOOKKEEPING_DB")
+    if env:
+        return Path(env).expanduser()
+    if (PROJECT_ROOT / "pyproject.toml").exists():
+        legacy = PROJECT_ROOT / "data" / "bookkeeping.db"
+        return legacy if legacy.exists() else PROJECT_ROOT / "data" / "keptwise.db"
+    return user_data_dir() / "keptwise.db"
+
+
+def user_data_dir() -> Path:
+    home = Path.home()
+    if sys.platform == "darwin":
+        return home / "Library" / "Application Support" / "Keptwise"
+    if sys.platform == "win32":
+        return Path(os.environ.get("APPDATA", home / "AppData" / "Roaming")) / "Keptwise"
+    return Path(os.environ.get("XDG_DATA_HOME", home / ".local" / "share")) / "keptwise"
+
+
+MIGRATIONS: list[str] = [
+    # 1: initial schema
+    """
+    CREATE TABLE categories (
+        id           INTEGER PRIMARY KEY,
+        name         TEXT NOT NULL UNIQUE COLLATE NOCASE,
+        bucket       TEXT NOT NULL CHECK (bucket IN ('regular','cash','investment','adhoc')),
+        invest_share REAL CHECK (invest_share IS NULL OR (invest_share >= 0 AND invest_share <= 1))
+    );
+
+    CREATE TABLE rules (
+        id          INTEGER PRIMARY KEY,
+        pattern     TEXT NOT NULL,
+        match_type  TEXT NOT NULL DEFAULT 'contains'
+                    CHECK (match_type IN ('contains','starts_with','exact','regex')),
+        direction   TEXT NOT NULL DEFAULT 'any' CHECK (direction IN ('any','in','out')),
+        tx_type     TEXT,
+        category_id INTEGER NOT NULL REFERENCES categories(id) ON DELETE CASCADE,
+        priority    INTEGER NOT NULL DEFAULT 0,
+        created_at  TEXT NOT NULL DEFAULT (datetime('now'))
+    );
+
+    CREATE TABLE imports (
+        id             INTEGER PRIMARY KEY,
+        filename       TEXT NOT NULL,
+        sha256         TEXT NOT NULL,
+        source         TEXT NOT NULL,
+        imported_at    TEXT NOT NULL DEFAULT (datetime('now')),
+        rows_total     INTEGER NOT NULL,
+        rows_added     INTEGER NOT NULL,
+        rows_duplicate INTEGER NOT NULL,
+        first_date     TEXT,
+        last_date      TEXT
+    );
+
+    CREATE TABLE transactions (
+        id          INTEGER PRIMARY KEY,
+        fingerprint TEXT NOT NULL UNIQUE,
+        date        TEXT NOT NULL,
+        tx_type     TEXT NOT NULL DEFAULT '',
+        description TEXT NOT NULL,
+        amount      INTEGER NOT NULL,
+        balance     INTEGER,
+        category_id INTEGER REFERENCES categories(id) ON DELETE SET NULL,
+        rule_id     INTEGER REFERENCES rules(id) ON DELETE SET NULL,
+        manual      INTEGER NOT NULL DEFAULT 0,
+        note        TEXT NOT NULL DEFAULT '',
+        import_id   INTEGER REFERENCES imports(id) ON DELETE SET NULL
+    );
+    CREATE INDEX ix_transactions_date ON transactions(date);
+    CREATE INDEX ix_transactions_category ON transactions(category_id);
+
+    CREATE TABLE settings (
+        key   TEXT PRIMARY KEY,
+        value TEXT NOT NULL
+    );
+    """,
+    # 2: links to investment accounts, and which investment is an ISA
+    """
+    ALTER TABLE categories ADD COLUMN url TEXT;
+    ALTER TABLE categories ADD COLUMN is_isa INTEGER NOT NULL DEFAULT 0;
+    UPDATE categories SET url = 'https://secure.vanguardinvestor.co.uk/', is_isa = 1
+        WHERE name = 'Index' AND bucket = 'investment';
+    UPDATE categories SET url = 'https://www.kraken.com/sign-in'
+        WHERE name = 'BTC' AND bucket = 'investment';
+    """,
+    # 3: fewer ad hoc categories (see categories.simplify)
+    "keptwise.categories:simplify",
+]
+
+
+def connect(path: Path | str | None = None) -> sqlite3.Connection:
+    """Open (and migrate) the database. ``":memory:"`` is supported for tests."""
+    path = default_db_path() if path is None else path
+    if str(path) != ":memory:":
+        Path(path).parent.mkdir(parents=True, exist_ok=True)
+        if _needs_upgrade(Path(path)):
+            backup(path, force=True)  # always keep a copy from before an upgrade
+    conn = sqlite3.connect(str(path), detect_types=0, check_same_thread=False)
+    conn.row_factory = sqlite3.Row
+    conn.execute("PRAGMA foreign_keys = ON")
+    migrate(conn)
+    return conn
+
+
+def _needs_upgrade(path: Path) -> bool:
+    if not path.exists() or path.stat().st_size == 0:
+        return False
+    conn = sqlite3.connect(str(path))
+    try:
+        version = conn.execute("PRAGMA user_version").fetchone()[0]
+    finally:
+        conn.close()
+    return 0 < version < len(MIGRATIONS)
+
+
+def migrate(conn: sqlite3.Connection) -> None:
+    version = conn.execute("PRAGMA user_version").fetchone()[0]
+    for index, script in enumerate(MIGRATIONS[version:], start=version + 1):
+        if script.startswith("keptwise."):
+            # A Python migration, written as "module:function".
+            import importlib
+
+            module, func = script.split(":")
+            with conn:
+                getattr(importlib.import_module(module), func)(conn)
+                conn.execute(f"PRAGMA user_version = {index}")
+            continue
+        with conn:
+            conn.executescript(script)
+            conn.execute(f"PRAGMA user_version = {index}")
+
+
+@contextmanager
+def transaction(conn: sqlite3.Connection) -> Iterator[sqlite3.Connection]:
+    """Commit on success, roll back on error."""
+    try:
+        yield conn
+        conn.commit()
+    except Exception:
+        conn.rollback()
+        raise
+
+
+def get_setting(conn: sqlite3.Connection, key: str, default: str | None = None) -> str | None:
+    row = conn.execute("SELECT value FROM settings WHERE key = ?", (key,)).fetchone()
+    return row["value"] if row else default
+
+
+def set_setting(conn: sqlite3.Connection, key: str, value: str) -> None:
+    conn.execute(
+        "INSERT INTO settings(key, value) VALUES(?, ?) "
+        "ON CONFLICT(key) DO UPDATE SET value = excluded.value",
+        (key, value),
+    )
+
+
+def backup(path: Path | str | None = None, *, keep: int = 30, force: bool = False) -> Path | None:
+    """Copy the database into ``backups/`` next to it, at most once a day.
+
+    Uses SQLite's online backup, so it's safe while the app is running. Keeps the
+    newest ``keep`` copies. Returns the new backup's path, or None if none was made.
+    """
+    path = Path(default_db_path() if path is None else path)
+    if str(path) == ":memory:" or not path.exists():
+        return None
+    folder = path.parent / "backups"
+    folder.mkdir(exist_ok=True)
+    existing = sorted(folder.glob(f"{path.stem}-*.db"))
+    today = datetime.now().strftime("%Y%m%d")
+    if not force and any(p.stem.split("-")[-2] == today for p in existing):
+        return None
+    target = folder / f"{path.stem}-{datetime.now():%Y%m%d-%H%M%S}.db"
+    source = sqlite3.connect(str(path))
+    dest = sqlite3.connect(str(target))
+    try:
+        with dest:
+            source.backup(dest)
+    finally:
+        dest.close()
+        source.close()
+    for old in sorted(folder.glob(f"{path.stem}-*.db"))[:-keep]:
+        old.unlink()
+    return target

keptwise/demo.py

@@ -0,0 +1,128 @@
+"""A made-up year of transactions, for trying the app and for screenshots.
+
+Everything here is invented: the employer, landlord, amounts and dates. Only well-known
+public company names are used, so the starter rules recognise them as they would on a
+real statement.
+"""
+
+from __future__ import annotations
+
+import random
+import sqlite3
+from datetime import date, timedelta
+
+from .db import set_setting
+from .importer import ParsedTransaction, import_transactions
+from .investments import Platform, save_platforms
+
+PLATFORMS = [
+    Platform(None, "Index fund", 0.8, "https://www.vanguardinvestor.co.uk/", True, ["VANGUARD"]),
+    Platform(None, "Bitcoin", 0.2, "https://www.coinbase.com/", False, ["COINBASE"]),
+]
+
+GROCERIES = ["TESCO STORES 2231", "ALDI 114", "LIDL GB NEWTOWN", "SAINSBURYS S/MKT", "CO-OP GROUP"]
+EATING = ["GREGGS PLC", "COSTA COFFEE", "NANDOS NEWTOWN", "THE OLD OAK PUB", "PRET A MANGER"]
+SHOPPING = ["AMAZON.CO.UK*AB12CD", "ARGOS LTD", "BOOTS 0423", "PRIMARK NEWTOWN", "IKEA LTD"]
+TRANSPORT = ["STAGECOACH BUS", "TRAINLINE.COM", "GWR TICKETS", "UBER *TRIP"]
+OUTINGS = ["ODEON CINEMAS", "TICKETMASTER UK", "NATIONAL TRUST", "BOWLING WORLD"]
+
+
+def months_back(today: date, count: int) -> list[date]:
+    """The first day of each of the ``count`` whole months before ``today``'s month."""
+    first = today.replace(day=1)
+    result = []
+    for _ in range(count):
+        first = (first - timedelta(days=1)).replace(day=1)
+        result.append(first)
+    return list(reversed(result))
+
+
+def _month_end(first: date) -> date:
+    return (first.replace(day=28) + timedelta(days=4)).replace(day=1) - timedelta(days=1)
+
+
+def _pence(rng: random.Random, low: float, high: float) -> int:
+    return round(rng.uniform(low, high) * 100)
+
+
+def month_transactions(
+    first: date, rng: random.Random, index: int, last: bool
+) -> list[tuple[date, str, str, int]]:
+    """One month's made-up spending and income, without investments."""
+    end = _month_end(first)
+    days = end.day
+
+    def on(day: int) -> date:
+        return first.replace(day=min(day, days))
+
+    tx: list[tuple[date, str, str, int]] = [
+        (on(1), "FPO", "HOMES LETTINGS RENT", -72500),
+        (on(2), "DD", "OCTOPUS ENERGY", -6400 if index < 7 else -7150),  # a price rise
+        (on(4), "DD", "THAMES WATER", -3150),
+        (on(8), "DD", "VIRGIN MEDIA", -3000),
+        (on(9), "DD", "GIFFGAFF", -1000),
+        (on(12), "DD", "PUREGYM LTD", -2499),
+        (on(14), "DEB", "NETFLIX.COM", -1099),
+        (on(18), "DEB", "SPOTIFY", -1199),
+        (on(25), "FPI", "ACME LTD SALARY", 215000 + (12000 if index >= 9 else 0)),
+    ]
+    if first.month not in (2, 3):  # council tax is paid over ten months
+        tx.append((on(1), "DD", "NEWTOWN CITY COUNCIL", -11800))
+    for week in range(4):
+        day = 2 + week * 7
+        tx.append((on(day + rng.randint(0, 2)), "DEB", rng.choice(GROCERIES), -_pence(rng, 18, 55)))
+        tx.append((on(day + rng.randint(0, 5)), "DEB", rng.choice(EATING), -_pence(rng, 3, 24)))
+        tx.append((on(day + rng.randint(0, 5)), "DEB", rng.choice(TRANSPORT), -_pence(rng, 2, 9)))
+    for _ in range(rng.randint(1, 3)):
+        tx.append((on(rng.randint(1, days)), "DEB", rng.choice(SHOPPING), -_pence(rng, 6, 60)))
+    if rng.random() < 0.6:
+        tx.append((on(rng.randint(1, days)), "DEB", rng.choice(OUTINGS), -_pence(rng, 9, 40)))
+    if rng.random() < 0.5:
+        tx.append((on(rng.randint(1, days)), "CPT", "NOTEMACHINE NEWTOWN", -2000))
+    if rng.random() < 0.4:
+        tx.append((on(rng.randint(1, days)), "FPI", "VINTED", _pence(rng, 8, 30)))
+    if rng.random() < 0.4:
+        tx.append((on(rng.randint(1, days)), "FPO", "A FRIEND", -2000))
+    if first.month == 8:  # a summer trip
+        tx.append((on(3), "DEB", "EASYJET", -18900))
+        tx.append((on(3), "DEB", "AIRBNB * HMXYZ", -32400))
+    if last:  # something for the "needs a category" view
+        tx.append((on(20), "DEB", "SUMUP *MARKET STALL", -1250))
+    return tx
+
+
+def build(conn: sqlite3.Connection, *, months: int = 12, today: date | None = None) -> int:
+    """Fill an empty, seeded database with ``months`` months of made-up data.
+
+    Returns the number of transactions added.
+    """
+    if conn.execute("SELECT 1 FROM transactions LIMIT 1").fetchone():
+        raise ValueError("The demo needs an empty database.")
+    rng = random.Random(2026)  # the same demo every time
+    with conn:
+        save_platforms(conn, [Platform(**vars(p)) for p in PLATFORMS])
+        set_setting(conn, "bank_name", "your bank")
+        set_setting(conn, "setup_done", "1")
+
+    balance = 120000
+    kept_last_month: int | None = None
+    added = 0
+    starts = months_back(today or date.today(), months)
+    for index, first in enumerate(starts):
+        rows = month_transactions(first, rng, index, last=index == len(starts) - 1)
+        kept = sum(amount for _, _, _, amount in rows)
+        invest = max(kept_last_month if kept_last_month is not None else 30000, 0)
+        if invest:
+            day = first.replace(day=3)
+            for platform, text in ((PLATFORMS[0], "VANGUARD"), (PLATFORMS[1], "COINBASE")):
+                rows.append((day, "DEB", text, -round(invest * platform.share)))
+        kept_last_month = kept
+
+        parsed = []
+        for when, tx_type, description, amount in sorted(rows, key=lambda r: r[0]):
+            balance += amount
+            parsed.append(ParsedTransaction(when, tx_type, description, amount, balance))
+        name = f"demo-{first:%Y-%m}.csv"
+        result = import_transactions(conn, parsed, filename=name, source="demo", sha256=name)
+        added += result.rows_added
+    return added