Electricity bills combine meter data, time-of-use buckets, delivery rates, generation rates, credits, taxes, and riders into a document most households cannot independently check. Generic bill summaries can restate the total, but they rarely prove whether a charge follows the tariff that governed that exact billing period.
The problem is both personal and widespread. A nationally representative Consumer Reports survey of 2,146 U.S. adults found that 68% said home energy costs strained their household finances to some degree. PG&E says its gas and electric service reaches approximately 16 million people. Dedicated tariff-audit products exist for organizations; WattProof brings that line-by-line discipline into a consumer-readable flow.
WattProof turns a bill into a reviewable evidence record, then checks supported charges with deterministic arithmetic. A user uploads a native PDF, confirms every material extracted fact beside its page and printed quote, and receives a line-by-line reconciliation against archived official rate sources. Every supported result exposes its inputs, full-precision rate, formula, rounding rule, effective dates, and source. When WattProof lacks a governing rule or sufficient usage detail, it says cannot verify instead of inventing a rate or savings estimate.
The MVP deliberately handles one public anonymized PG&E delivery and Central Coast Community Energy generation statement exceptionally well. The authentic statement reconciles against its 2022 sources. A separate fixture is clearly labeled synthetic and changes one auditable peak charge by exactly $5.00, proving that the engine detects a known discrepancy without suggesting it occurred on a real customer's bill.
The complete flow is upload, evidence review, deterministic audit, honest plan-comparison sufficiency, and an editable review request grounded only in audit facts. Uploaded files are temporary, the app stores no customer data, and it never contacts a provider or sends the request automatically.
How it was built
WattProof is a small Python application: Flask serves a framework-free responsive interface; Pydantic defines the versioned extraction, evidence, tariff, audit, comparison, and review-request contracts; and Python Decimal code performs all money arithmetic with explicit half-up rounding. Official source snapshots are committed with retrieval metadata and SHA-256 hashes, and the engine refuses to calculate if a source changes.
GPT-5.6 uses schema-constrained OpenAI Responses API output to map unknown native-PDF text into typed evidence. It does not choose rates, calculate charges, or invent missing data. The bundled public sample is recognized by hash and runs entirely locally without an API key. A focused regression proves the model, strict Pydantic schema, disabled API storage, and trusted document-metadata boundary.
Codex drove the primary build session: it rendered and inspected the supplied documents, rejected unsuitable sample paths, researched matching effective-period sources, independently checked tariff math, designed the smallest architecture, implemented the engine and five-step UI, created golden and synthetic regression fixtures, diagnosed browser failures, and verified the final flow. CODEX_LOG.md preserves prompts, decisions, failures, corrections, verification results, and milestone commits.
What makes it different
- Effective-period truth: a newer tariff is not treated as better when it did not govern the bill.
- Evidence before automation: users can correct extracted facts before any conclusion is calculated.
- Deterministic money: GPT-5.6 reads evidence; typed code owns arithmetic.
- Visible uncertainty: unsupported riders and insufficient interval data remain explicit limitations.
- Action without overclaiming: the final request asks for review and cites the exact lines and sources involved.
Codex session ID: 019f7c01-1e1d-7681-a3bc-7276037d9ef7
Challenges and lessons
The hardest problem was not PDF parsing or interface polish. It was establishing trustworthy ground truth. I initially expected the newest rate source to be the best one, but the supplied current PG&E pricing summary is effective in 2026 while the auditable statement is from 2022. Applying the current rates would have produced a polished but false demo. A July 19, 2026 search found newer guidance but no newer complete ordinary residential sample with a coherent matching rate source, so WattProof uses the newest coherent public bill-and-tariff pair found and explains that choice.
That constraint shaped the product: provenance is executable, arithmetic is reproducible, uncertainty survives extraction, and the comparison step refuses to annualize one aggregate month or reconstruct time windows it cannot observe.
Built With
- codex
- flask
- gpt-5.6
- javascript
- openai-api
- pydantic
- python
Log in or sign up for Devpost to join the conversation.