Skip to content
HashirABDPublic

About

Rule-check tool for utility catch-up bills. Code does the money math; AI only reads bills and helps with letter wording. Draft output, not legal advice.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

Β 

History

47 Commits

Folders and files

Repository files navigation

BillRightΒ BillRight logo

An AI-assisted consumer rule-check web utility that checks whether a utility catch-up bill appears to fall outside the back-billing window set by the rules it covers across multiple jurisdictions (UK, Australia, US), featuring multimodal bill & physical meter dial OCR, interactive SVG timeline visualization, deterministic pro-rata math, direct supplier email dispatch, escalation calendar reminders (.ics), dynamic party personalization, and multi-page vector dispute packet generation (.pdf).

BillRight Node.js Architecture Multimodal PDF Engine Calendar Engine License

🌐 Live Demo: https://billright-zeta.vercel.app
πŸ“Ί Demo Video: https://youtu.be/loW62sx7xaM
πŸ“‹ Planning Docs: scope.md β€’ prd.md β€’ spec.md β€’ checklist.md


What BillRight Does

In many countries and states, energy utility regulators legally restrict how far back suppliers can bill consumers for historical energy consumption:

  • United Kingdom: Under Ofgem Standard Licence Condition 21BA, energy suppliers cannot demand payment for energy consumed more than 12 months prior to the bill date. However, Ofgem SLC 21BA has exceptions (for example where the customer has obstructed the supplier), so the result is a rule check, not a final answer.
  • Australia: Under NERR Rule 30 (National Energy Retail Rules for participating states such as NSW, QLD, SA; Victoria maintains separate local rules), retailers recovering historical undercharges are strictly capped at a maximum of 9 months before the customer was notified.
  • United States (California): Under PG&E Electric Rule 17.1 (and equivalent CPUC tariff rules for SCE/SDG&E), adjustment of residential bills for billing errors where the customer was not at fault is restricted to 3 months.
  • United States (Texas): Under PUCT Β§25.28(d) for electric utilities, back-billing adjustments are limited to 6 months from error discovery; for retail electric providers, the limit under Β§25.480(e) must be verified with the PUCT.

Despite these protections, millions of households, tenants, and small businesses receive sudden, intimidating multi-year catch-up bills. Most either panic and pay or struggle to dispute them because utility regulations are dense, suppliers provide estimated meter readings that inflate charges, and consumers miss critical statutory escalation deadlines.

BillRight empowers consumers by:

  1. Reading Statements & Meters Honestly: Uses Gemini Vision to extract statement dates, billing periods, amounts, and physical meter index readings, always leaving the user in control to inspect, edit, or enter values manually.
  2. Calculating Disputable Amounts Deterministically: Apportions charges day-by-day across statutory lookback cut-off dates using zero-dependency, pure mathematical calculation. The AI is never permitted to calculate numbers or dates.
  3. Visualizing Lookback Windows: Renders an interactive SVG timeline showing the Permitted Window and the Disputable Window, with cut-off barrier line and pro-rata period slices.
  4. Generating Dispute Packets (draft): Formulates formal dispute letters citing exact statutory rules, caveats for meter obstruction or estimated readings, and packages a 3-page vector PDF packet with full mathematical schedules.
  5. Managing Escalation Calendars & Inboxes: Computes Day 1 (today), Day 14 (suggested response deadline), and Day 56 (8-week Ombudsman escalation) from the user's local date, providing one-click .ics calendar reminders and pre-filled complaints email dispatch.

Anti-Hallucination Architecture

                          USER INTERACTION
    β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
    β”‚  PDF / Image Dropzone β”‚  Manual / Preset Input Form   β”‚
    β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                β”‚                           β”‚
                β–Ό                           β”‚
    β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”           β”‚
    β”‚  POST /api/extract-bill   β”‚           β”‚
    β”‚  Gemini Vision OCR        β”‚           β”‚
    β”‚  (Structured JSON schema) β”‚           β”‚
    β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜           β”‚
                β”‚ (Auto-populates fields)   β”‚
                └──────────────────────────►▼
                                β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
                                β”‚     POST /api/analyze     β”‚
                                β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                                              β”‚
    β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
    β–Ό                                         β–Ό                                        β–Ό
[Stage 1: Deterministic Math]        [Stage 2: Live Search]                  [Stage 3: Constrained LLM]
calculateBackBilling.js              tavilyClient.js                         llmClient.js
- Regional lookback:                 - UK: Ofgem SLC 21BA                    - Exception evaluation
  β€’ UK: 12 months                    - AU: NERR Rule 30 (9 mos)              - Multi-currency letter
  β€’ AU: 9 months                     - US CA: PG&E Rule 17.1 (3 mos)         - Localized ombudsman
  β€’ US TX: 6 months                  - US TX: PUCT Β§25.28(d)/Β§25.480(e)        escalation pathways
- Daily pro-rata apportionment       - Dynamic query builder                 - Obstruction warnings
                                              β”‚
                                              β–Ό
                                 UNIFIED CLIENT RESPONSE
                                              β”‚
       β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
       β–Ό                                                                             β–Ό
[Interactive SVG Timeline]                                              [Results & Action Deck]
- Color-coded zones (Permitted vs Disputable)                           - Semantic Badges
- Cut-off barrier line with exact date                                  - Itemized pro-rata table
- Straddling period split segments                                      - Live citation cards
- Hover tooltips & interactive highlights                               - One-click copyable letter

Supported Jurisdictions

Jurisdiction Regulatory Body Statutory Instrument Lookback Limit Currency Escalation Ladder
United Kingdom Ofgem Standard Licence Condition 21BA 12 months Β£ (GBP) Supplier complaint (8 wks) β†’ Energy Ombudsman
Australia AER National Energy Retail Rules (NERR Rule 30) 9 months A$ (AUD) Retailer dispute β†’ Energy & Water Ombudsman (EWON/EWOV/EWOQ)
US (California) CPUC PG&E Electric Rule 17.1 (SCE/SDG&E eq.) 3 months $ (USD) Utility complaint β†’ California Public Utilities Commission
US (Texas) PUCT Β§25.28(d) electric utilities (6 mos); Β§25.480(e) REPs (must be verified with PUCT) 6 months (utilities; verify REP limit) $ (USD) Utility dispute β†’ Public Utility Commission of Texas
Other Country Regional Regulator Provisional 12-month benchmark 12 months (Provisional) $ (USD) Regional regulatory authority

Instant Sample Presets

BillRight includes instant presets for one-click demonstration:

  • UK Case A (Β£1,400 Catch-up Bill): Billed energy exceeds 12 months; produces an emerald "Likely not recoverable under the rule" badge, Β£1,000.00 disputable charges, Ofgem SLC 21BA citation, and a formal dispute letter.
  • UK Case B (Β£650 Recent Charge): Charges fall strictly within the permitted 12-month window; produces a slate "Rule does not apply" badge.
  • AU Case D (A$1,800 Catch-up Bill): 18-month catch-up bill in Australia; enforces NERR Rule 30 9-month limit, isolating A$900.00 disputable charges and drafting an Ombudsman escalation letter.
  • US CA Case E ($900 Underbilling): 9-month billing adjustment in California; enforces PG&E Rule 17.1 3-month limit, isolating $600.00 in disputable charges.
  • Case C (Missing Data): Demonstrates form validation behavior when dates are absent.

How to Run Locally

Prerequisites

  • Node.js (v18 or higher)
  • npm

1. Clone the repository

git clone https://github.com/HashirABD/billright.git
cd billright

2. Install dependencies

npm install

3. Configure environment variables

Copy the sample environment file:

cp .env.example .env

Edit .env:

PORT=3000
GEMINI_API_KEY=your_gemini_api_key_here
GEMINI_MODEL=gemini-3.8-flash
GEMINI_FALLBACK_MODELS=gemini-3-flash,gemini-3.1-flash-lite,gemini-3.5-flash-lite
TAVILY_API_KEY=your_tavily_api_key_here

(Get a free Gemini API key from Google AI Studio and a free Tavily API key from Tavily.)

4. Run the development server

npm start

Open http://localhost:3000 in your browser.


Testing

Run the deterministic mathematical unit test suite:

npm run test:math

The unit tests check the date and apportionment math against fixed example cases (cut-off dates, calendar day counting, multi-period composite math, straddling pro-rata formulas, leap year clamps, timezone edge calculations, obstruction/estimate handling, and multi-model quota fallback). The tests check that the code runs as intended; they do not prove that the legal rules or regulatory interpretations are correct.


How the Devpost Skill Pack Was Used

BillRight was developed following the structured Build With AI: Basics methodology using specialized agent skills:

  1. 1-start: Established the learner profile, project conventions, and the flipped-interaction workflow, ensuring the agent interviews the builder to uncover core requirements.
  2. 2-scope: Interrogated the problem space to isolate a high-impact proof of concept: helping consumers dispute back-billing without hallucinations. Defined the non-negotiable boundary: AI handles extraction and text formatting, but pure code handles math.
  3. 3-prd: Authored a complete product requirements document covering user journeys, multimodal inputs, edge cases (leap years, meter obstructions, estimated bills), and multi-jurisdiction statutory rules without premature code discussion.
  4. 4-spec: Drafted the technical blueprint: Express.js server, vanilla CSS/JS frontend, zero-dependency math engine (calculateBackBilling.js), Gemini Vision for multimodal OCR, Tavily for live citation grounding, and PDFKit for vector dispute packets.
  5. 5-build: Executed vertical slices step-by-step: Slice 1 (deterministic math), Slice 2 (form UI and SVG timeline), Slice 3 (multimodal bill and meter dial OCR), and Slice 4 (PDF export, email launcher, and calendar integration), checking each milestone with unit tests.
  6. 6-ship: Conducted end-to-end testing, ran test suites, resolved regulatory citations, eliminated hardcoded mock data, secured credentials, and deployed live to Vercel.

Planning Docs

  • devpost/scope.md β€” Proof of concept boundary and scope definition
  • devpost/prd.md β€” Core user journey, behavioral requirements, and edge cases
  • devpost/spec.md β€” Technical blueprint, deterministic math engine, and multimodal architecture
  • devpost/checklist.md β€” Verification checklist and shipping criteria

Data Privacy & File Handling

BillRight does not store your files. They are sent to Google Gemini for reading and are subject to Google's data policy.


Known Limits

  • AI Quota & Fallbacks: The AI reader and letter wording use the Google Gemini free tier, which has a small daily request limit per model. The app tries fallback models (GEMINI_FALLBACK_MODELS) and, if all are exhausted, shows a "busy" message for bill reading and falls back to a built-in dispute letter template.
  • Jurisdiction Coverage: The rule check covers only the jurisdictions in the table above. All other regions fall back to an unverified provisional benchmark.
  • Draft Output, Not Legal Advice: Output is a draft for the user to review, not legal advice or a formal ruling.

Notice & Informational Disclaimer

Not legal advice. BillRight is an informational consumer calculation tool designed to assist consumers in identifying catch-up utility charges and assembling formal dispute notices. It does not provide legal advice, judicial decisions, or financial guarantees. Consumers should verify official utility rules with their regional energy regulator (e.g. Ofgem, AER, CPUC, PUCT) or independent ombudsman service.


Future Work

  • Dual-Fuel Splitting: Separate gas and electricity tariffs, standing charges, and calorific value conversions on combined utility statements.
  • Supplier API Inboxes: Direct REST integrations with energy supplier customer service ticketing systems for automated delivery confirmation and tracking.
  • Multi-Language Notices: Localized statutory dispute letters in Spanish, Welsh, and other regional languages.
  • Ombudsman Case Tracking: Webhook-based tracking for the standard 8-week complaints timeframe with automated status notifications.

License

MIT License. See LICENSE for details.

About

Rule-check tool for utility catch-up bills. Code does the money math; AI only reads bills and helps with letter wording. Draft output, not legal advice.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages