README.md

---
title: PUE Report Generator
emoji: 📄
colorFrom: green
colorTo: blue
sdk: streamlit
sdk_version: 1.40.0
app_file: app.py
pinned: false
---

# PUE Report Generator

Upload a community **PUE master-sheet** workbook and download a
template-faithful Word report. Every figure in the report is recomputed
deterministically from the sheet — the (optional) AI step only ever rewrites
prose, never numbers.

## Use it

1. Upload the master sheet (`.xlsx`).
2. Set the developer name, report date, and any developer-supplied mini-grid
   capacities (only if they aren't already in the sheet).
3. Click **Generate report** and download the `.docx`.

## Pipeline

```
master.xlsx --extract--> PUEReportData --recompute--> --validate--> (+warnings)
                                |
                                +-- generate_narratives (LLM, prose only)
                                +-- render (deterministic .docx)
```

## AI narratives (optional)

The three prose sections can be written by Gemini. To enable them, add a
`GOOGLE_API_KEY` secret to the Space (Settings -> Variables and secrets) and
switch on the toggle in the sidebar. Without a key, those sections use a plain
deterministic fallback and everything else works unchanged.

## Run locally

```bash
pip install -r requirements.txt
streamlit run app.py
```

(Developer/internals notes are in `DEVELOPER_NOTES.md`.)