Keep the household paperwork straight

A household has a folder of documents and a short list of things that cost money every month: an insurance policy, a water bill, a power bill, broadband, a gym, a storage unit, a reading subscription somebody signed up for and forgot. The questions are always the same four. What renews itself in the next few weeks, and at what price. What is owed right now, and what is already late. What all of it costs in a year, and which part of it is the expensive part. And where the document is, on the morning somebody needs it.

None of that needs a model. What renews soon is a date subtracted from another date. What is owed is a filter on a flag. What the year costs is a multiplication and a sum. Where the document is is a naming rule and a set difference. A spreadsheet, a calendar and a folder rule answer all four questions, every time, for nothing, and they are right in a way nothing that reads text can promise to be.

There is one part of household paperwork that does need a model, and this recipe deliberately does not do it: turning a photographed or scanned bill into a record with a provider, an amount and a date. That job is turning photos and PDFs into records, and the business version of the same seam is matching invoices to purchase orders. Everything after the record exists is this page.

Example run

11 records (provider, category, amount in cents, period,
date, auto-renew, paid) and the 11 files in the folder

Walkthrough

The report runs for a date, not for “today”: run reads that date out of the request and refuses a request that names no date at all, rather than answering for a day the reader did not mean. The five steps are the five questions, in order, and each one records what it found.

def run(asked: str, model: Model | None, tracer: Tracer, *, records=RECORDS, folder=FOLDER) -> Report:
    del model  # level 0: nothing here calls a model, and the pass or fail of a date is not a judgment
    as_of = as_of_from(asked)
    tracer.record(kind="code", decided_by="code", title="Read the records",
                  detail=f"{len(records)} records, {len(folder)} files, as of {as_of.isoformat()}")

    renewals = renewals_due(records, as_of)
    tracer.record(kind="code", decided_by="code", title=f"Sort by date, keep the next {RENEWAL_WINDOW_DAYS} days",
                  detail=", ".join(f"{r.id} {r.due.isoformat()}" for r in renewals) or "none")

    unpaid = unpaid_bills(records, as_of)
    tracer.record(kind="code", decided_by="code", title="Filter the unpaid rows and flag the late ones",
                  detail=", ".join(f"{r.id}{' late' if late else ''}" for r, late in unpaid) or "none")

    by_category = yearly_by_category(records)
    tracer.record(kind="code", decided_by="code", title="Normalize every amount to a year and sum by category",
                  detail=", ".join(f"{cat} {money(total)}" for cat, total in by_category.items()))

    unreadable, undocumented = misfiled(records, folder)
    tracer.record(kind="code", decided_by="code", title="Check the folder against its naming rule",
                  detail=f"{len(unreadable)} unreadable name(s), {len(undocumented)} record(s) with no document")

    return Report(
        as_of=as_of,
        renewals=tuple(renewals),
        unpaid=tuple(unpaid),
        by_category=by_category,
        largest=tuple(largest_yearly(records)),
        unreadable_files=tuple(unreadable),
        undocumented=tuple(undocumented),
    )

Against the eleven invented records, run for 09/19/2026, that produces: five auto-renewing commitments inside the next 30 days, the first on 10/01 and the largest on 10/02 at $1,184.00; one overdue bill, Kestrel Power at $147.80, dated 09/12; one more due on 10/14; a yearly total of $5,860.28, of which utilities are $3,014.40 and subscriptions $863.88; and three gaps in the folder, two files whose names cannot be searched by date or provider and one commitment with no document filed against it at all.

That last group is the one people underestimate. A policy that is filed under a name nothing can search by does nobody any good on the morning of a claim. The rule is a regular expression, and the check is a set difference:

def misfiled(records, folder) -> tuple[list[str], list[Record]]:
    """Two ways a document is not there when it is needed: a file whose name breaks the folder's
    rule, and a record with no document filed against it at all."""
    unreadable = sorted(name for name in folder if not FILE_RE.match(name))
    missing = [r for r in records if r.document is None or r.document not in folder]
    return unreadable, missing

Two details in the code are deliberate. Money is integer cents everywhere, because a budget in floating point drifts by a cent or two and produces a total nobody can reconcile against their own statements. And a one-off cost, a warranty bought once, counts as zero in the yearly totals rather than being folded in as though it recurred: the report says what it left out.

What it costs

Illustrative, not measured: no result file exists for this technique yet, so every number below is a worked example. See docs/EVALS.md for how a real run is recorded and scored.

The unit here is per report, and a household reads this one weekly at most. That is what makes the cost argument for level 0 an argument about correctness rather than about money. A few thousand tokens a year is nothing to anybody. A yearly total that is off by one subscription, on the one page a household uses to decide what to cancel, is the whole point of the exercise gone.

How it fails

The failures here are data problems, not model problems. That is the honest shape of a level-0 recipe: nothing can hallucinate, and everything can be missing.

What to measure

There is no model here, so there is nothing to score and no eval set to build. What there is to check is the data, and the check is a reconciliation: take one month of statements, and confirm that every charge on them appears in the records and that every record’s amount matches. Do it once when the records are first entered and once a year after that. Two numbers are worth writing down while you do it: how many charges were missing from the records, and how many amounts had drifted since they were entered. Both are measures of the folder, not of any technique.

The one test that is worth automating is the arithmetic itself, which is what this example’s test file does: the window’s boundaries, each period’s multiplier, and the category totals recomputed from the records rather than read back from the report. A total the code and the check both got from the same call proves nothing.

Variations

• Do it in a spreadsheet. One row per commitment, a column for the yearly figure, a filter on the date, and a conditional format for anything unpaid. The reasoning on this page carries over exactly; nothing about it needs Python.
• Add a reminder by making the report run on a schedule and send itself. That is a timer, not a level: see the nightly source monitor for the same argument about a schedule being infrastructure rather than agency.
• Feed the records from document extraction once the folder is large enough that typing each one in is the bottleneck, and keep a person on the confirm step: an amount read wrong flows into every total on this page.
• Ask questions of it in words, rather than reading the report, once the records outgrow one screen. That is document Q&A at level 2, and it is a different job: answering a question, not producing the same page every week.

Design choices

def renewals_due(records, as_of: date, *, window_days: int = RENEWAL_WINDOW_DAYS) -> list[Record]:
    """Anything that renews itself on or before `as_of + window_days`, soonest first. The window
    is inclusive at both ends: a renewal on the last day of it is the one worth catching."""
    last = as_of + timedelta(days=window_days)
    due = [r for r in records if r.auto_renew and as_of <= r.due <= last]
    return sorted(due, key=lambda r: (r.due, r.id))

def yearly_cents(record: Record) -> int:
    """What this record costs in a year. A period nobody priced yearly is zero, not a guess."""
    return record.amount_cents * PER_YEAR.get(record.period, 0)