Savings Insight

The Savings Insight service takes a customer's electricity usage history and address, then produces a personalised solar savings report — combining real roof data, state-specific rates, and Gemini-generated content into a PDF delivered to the customer by email.

Processing pipeline

Inputs

Input	Source	Used for
Monthly usage history	Utility Bill AI	Annual kWh total, seasonal patterns, and sizing the solar system to offset ~100% of consumption.
Service address	Widget / customer input	Geocoded to lat/lng for Google Solar API lookup and state rate selection.
Customer name	Widget / customer input	Personalises the Gemini-generated report content.
State rates	Metiss database	State average electricity rate ($/kWh) and escalator rate, used in financial projections.
Google Solar API	Google Building Insights	Roof area (m²), max sunshine hours/year, panel capacity, and yearly energy potential (DC kWh).

Calculations

The service performs all financial modelling before handing off to Gemini:

Metric	How it is calculated
Total annual kWh	Sum of the 12 monthly usage values from the utility bill extraction.
Annual electricity cost	Total annual kWh × state average electricity rate.
Proposed system size	Targeted at 10 kW DC, adjusted to offset approximately 100% of annual usage based on roof yield data.
Gross system cost	System size (W) × state average solar cost per watt.
Net system cost	Gross cost after 30% Federal Investment Tax Credit (ITC).
Net annual savings	Annual electricity cost offset by the solar system, adjusted for state-specific program charges.
Payback period	Net system cost ÷ net annual savings.

Report sections

Gemini generates a JSON response containing HTML-formatted sections. The service validates the structure before rendering it to PDF.

Section	Content
I — Executive Summary	Overview of the customer's current electricity spend, solar opportunity, and key headline savings figure. References state-specific efficiency programmes (e.g. Mass Save®, Energize CT).
II — Usage Analysis	Breakdown of the customer's monthly and annual consumption patterns, peak months, and year-on-year cost projection.
III — Solar Recommendation	Recommended system size, annual production estimate, financial analysis (gross cost, ITC, net cost, payback), projected annual savings, additional benefits (property tax exemption, net metering), financing options, and battery storage incentives — all state-specific where known.

State-specific content:Gemini is given the customer's state abbreviation and instructed to use known local rates, programme names, and incentives. For states where Gemini lacks specific data, nationally applicable averages and generic programme descriptions are used.

API endpoints

Method & path	Purpose	Returns
`POST /savings-insight-report`	Full pipeline — calculates, generates report, and triggers email + PDF.	Report JSON + transaction ID.
`POST /generate-savings-insights`	LLM report generation only. Skips solar calculation — caller provides pre-computed data.	Validated report sections JSON.
`POST /generate-pdf-report`	Renders an existing LLM response to a PDF and returns it as a stream.	PDF binary stream.
`GET /health`	Health check.	`{'status': 'ok'}`

Report response structure

{
  "data": {
    "items": [
      {
        "report": {
          "sections": [
            {
              "sequence": "I",
              "title": "Executive Summary",
              "text": "<p>Based on your usage of ...</p>"
            },
            {
              "sequence": "II",
              "title": "Usage Analysis",
              "text": "..."
            },
            {
              "sequence": "III",
              "title": "Solar Recommendation & Financial Analysis",
              "text": "..."
            }
          ]
        }
      }
    ]
  }
}

Section text is HTML. The text field in each section contains HTML markup (<p>, <ul>, <strong>, etc.) ready to render directly in the PDF template or a web view.