Upload 15 files

.gitignore

@@ -0,0 +1,5 @@
+__pycache__/
+*.pyc
+*.xlsx
+*.docx
+.DS_Store

DEVELOPER_NOTES.md

@@ -0,0 +1,155 @@
+# PUE Report Agent
+
+Turns a DREEF **Productive Use of Energy (PUE) master-sheet** workbook into a
+community PUE report, using LangChain for the *prose* and deterministic Python
+for *every number*.
+
+This skeleton was reverse-engineered from two real report/master-sheet pairs
+(Jaji and Kwarua Tasha, both Kaduna State). It already extracts cleanly from
+both.
+
+---
+
+## Why it's split the way it is
+
+The single most important design decision: **the LLM never touches a number.**
+
+When a report's figures are re-typed by a language model, they drift — that is
+literally how one of the source reports ended up with budget and equipment
+numbers that didn't match its own master sheet. So the architecture is:
+
+```
+master.xlsx
+   │
+   ▼  extractors.py          (pure Python, openpyxl — deterministic)
+PUEReportData
+   │
+   ▼  calc.py                (recompute every total from line items)
+PUEReportData (correct totals)
+   │
+   ▼  validate.py            (reconciliation; appends warnings)
+PUEReportData (+warnings)
+   │
+   ├─►  agent.py  generate_narratives()    LLM — PROSE ONLY
+   │      • Community Overview  ............  Gemini  (gemini-1.5-pro)
+   │      • Demographic narrative  .........  Gemini
+   │      • Processing Insights  ...........  Gemini
+   │
+   ▼  render.py              →  template-faithful .docx
+```
+
+* **`schema.py`** — Pydantic models. The contract between every stage.
+* **`extractors.py`** — reads the workbook into the schema. Numbers come from
+  here, never from an LLM. Budget extraction is header-aware (each section maps
+  its own columns), so irregular blocks like "OTHERS" parse correctly.
+* **`calc.py`** — recomputes every total from its line items: budget section
+  totals, BOQ grand total, equipment kW/quantity totals, energy projections,
+  financial-model monthly totals. The template shipped with a Grand Total of
+  ₦30,756,000 when its line items summed to ₦37,256,000; the agent never
+  reproduces that kind of error, and records any disagreement as a warning.
+* **`validate.py`** — checks interview counts agree, flags stale template text.
+* **`templates.py`** — the boilerplate sections, verbatim from the reference
+  template (introduction, methodology, infrastructure specs, governance, safety,
+  conditions for scale-up, MER, risks, SDGs, challenges, AI disclosure), filled
+  with `str.format`. Never sent to a model.
+* **`agent.py`** — the only LLM code. All three narratives (Community Overview,
+  demographic, processing insights) are generated with **Gemini**
+  (`gemini-1.5-pro`). The model is swappable per call, so individual chains can
+  move to another provider later without changing the chains.
+* **`render.py`** — produces a Word document that mirrors the reference
+  template's structure exactly.
+
+## What `render.py` reproduces from the template
+
+* **Title page** in the template's layout.
+* **Auto Table of Contents** — a real Word TOC field that builds and renumbers
+  itself on open.
+* **Auto List of Tables** — a Word Table-of-Figures field keyed to the "Table"
+  caption sequence.
+* **SEQ-field caption numbering** — every caption is `Table ` + a `SEQ Table`
+  field (or `Figure ` + `SEQ Figure`). Word computes the numbers, so they are
+  always sequential and correct no matter how many tables a community needs —
+  nothing is hard-numbered.
+* **Every section in template order** with the template's headings and tone.
+* **Community-adaptive tables** — one machinery table per processed crop, one
+  equipment table per section, one budget table per section, each with a
+  recomputed TOTAL row. The skeleton stays identical; the rows follow the data.
+* Fields are set to **update on open**, so the TOC, List of Tables and all
+  caption numbers populate the first time the file is opened in Word.
+  (LibreOffice's headless PDF convert doesn't run that update — open in Word, or
+  press Ctrl+A then F9, to populate them.)
+
+---
+
+## Quick start
+
+```bash
+pip install -r requirements.txt
+
+# Extraction + recompute + validation + render — no API key needed.
+# Narratives are skipped with --no-llm, but the full template still renders:
+python run.py "Jaji-_Kaduna_PUE_Master_Sheet.xlsx" --no-llm \
+    --developer "Green Edge Consortium" --date "February 2026" \
+    --solar-pv "6.45 MWp" --battery "10 MWh" \
+    --docx-out jaji_report.docx
+
+# Full run with AI narratives (all narratives use Gemini):
+export GOOGLE_API_KEY=...
+python run.py "Jaji-_Kaduna_PUE_Master_Sheet.xlsx" \
+    --developer "Green Edge Consortium" --date "February 2026" \
+    --docx-out jaji_report.docx --json-out jaji.json
+```
+
+Open the resulting `.docx` in Word; the Table of Contents, List of Tables and
+all caption numbers populate automatically on first open.
+
+---
+
+## What the data layers in the master sheet mean
+
+| Layer | Sheets | Role |
+|-------|--------|------|
+| Raw survey | `Minigrid Farmers Input`, `Processors`, `SME`, `E-Mobility`, `Market`, `ESG` | One row per respondent |
+| Analysis | `* Analysis Sheet` | Pre-aggregated label/value blocks |
+| **Key Findings** | `Key Findings` | Report-ready tables (the extractor's main source) |
+| Equipment / Budget / Finance | `Proposed * PUE Equipment`, `Budget`, `Individual Model`, `Agrohub Model`, `Summary` | Plans & costs |
+
+The extractor prefers raw/analysis sheets for survey facts and only uses Key
+Findings for **developer-supplied** figures (capacities, revenue-per-user,
+projected impact) that aren't derivable from survey data — because Key Findings
+is where stale template text from other communities tends to survive.
+
+### Things that are NOT in the survey data
+* Mini-grid capacities (Solar PV / Battery / Annual Consumption) — developer input.
+* Revenue-per-user table — developer input, often shared across communities.
+Pass these in explicitly; the validator warns if they're missing.
+
+---
+
+## Extending to a new community / new sheet layout
+
+1. Run `python run.py new_sheet.xlsx --no-llm`.
+2. Read the warnings and eyeball the summary against the source.
+3. If a block comes back empty, the label probably moved. The extractor finds
+   blocks by **label text scanned across all columns** (`_label_col`) rather
+   than fixed cell addresses, so usually only the label string needs updating.
+4. Add a `validate.py` check for any new invariant you discover.
+
+## Adapting to a community whose data is shaped differently
+
+The renderer is data-driven, so new crops, new SME types, more or fewer budget
+sections, etc. flow through automatically — the template skeleton stays fixed
+while the rows follow the master sheet. The two things to supply per community
+that are NOT in the survey data:
+
+* **Mini-grid / micro capacities** (Solar PV, battery, annual consumption,
+  distribution metrics) — developer figures; pass via the CLI flags or set
+  `data.minigrid` / `data.microgrid` before rendering.
+* **Report date** for the title page (`--date`).
+
+---
+
+## Tested against
+* `Jaji-_Kaduna_PUE_Master_Sheet.xlsx` — clean extraction, 3 advisory warnings.
+* `Kwarua_Tasha_-_Kaduna_PUE_Master_Sheet.xlsx` — clean extraction, 6 warnings
+  correctly flagging real defects in that workbook.

README.md

@@ -0,0 +1,49 @@
+---
+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`.)

app.py

@@ -0,0 +1,146 @@
+"""
+Streamlit front-end for the DREEF PUE report generator.
+
+Upload a community master-sheet workbook, set the developer / date (and any
+externally-supplied mini-grid capacities), and download a template-faithful
+Word report. Optional AI narratives use Gemini and require GOOGLE_API_KEY.
+
+Run locally:   streamlit run app.py
+Deploy:        push this folder to a Hugging Face Space (SDK = Streamlit).
+"""
+from __future__ import annotations
+
+import os
+import tempfile
+from io import BytesIO
+
+import streamlit as st
+
+from pue_report_agent import extract_master_sheet, recompute, validate
+
+st.set_page_config(page_title="PUE Report Generator", page_icon="📄",
+                   layout="centered")
+
+st.title("📄 PUE Report Generator")
+st.caption(
+    "Turn a community PUE master-sheet workbook into a template-faithful Word "
+    "report. Every number is recomputed from the sheet — the AI only ever "
+    "touches prose, never figures."
+)
+
+# --------------------------------------------------------------------------- #
+# Sidebar — options
+# --------------------------------------------------------------------------- #
+with st.sidebar:
+    st.header("Report settings")
+    developer = st.text_input("Mini-grid developer",
+                              value="the mini-grid developer")
+    report_date = st.text_input("Report date (title page)", value="")
+
+    st.subheader("Mini-grid capacities")
+    st.caption(
+        "Developer-supplied; only fill these if they aren't already in the "
+        "sheet's Key Findings."
+    )
+    solar_pv = st.text_input("Solar PV", value="", placeholder="e.g. 6.45 MWp")
+    battery = st.text_input("Battery storage", value="", placeholder="e.g. 10 MWh")
+    annual_consumption = st.text_input("Annual consumption", value="",
+                                       placeholder="e.g. 5 MW")
+
+    st.subheader("AI narratives")
+
+    def _has_api_key() -> bool:
+        if os.environ.get("GOOGLE_API_KEY"):
+            return True
+        try:
+            return bool(st.secrets.get("GOOGLE_API_KEY"))
+        except Exception:
+            return False
+
+    has_key = _has_api_key()
+    want_narratives = st.toggle(
+        "Generate AI prose sections (Gemini)", value=False,
+        help="Needs GOOGLE_API_KEY in the Space secrets or environment. "
+             "Without it, the three prose sections use a plain fallback.")
+    if want_narratives and not has_key:
+        st.warning("No GOOGLE_API_KEY found — narratives will be skipped.")
+
+# --------------------------------------------------------------------------- #
+# Main — upload & generate
+# --------------------------------------------------------------------------- #
+uploaded = st.file_uploader(
+    "Upload the PUE master sheet (.xlsx)", type=["xlsx", "xlsm"])
+
+if uploaded is None:
+    st.info("Upload a master-sheet workbook to begin.")
+    st.stop()
+
+if st.button("Generate report", type="primary"):
+    with st.spinner("Extracting, recomputing, validating…"):
+        # extract_master_sheet expects a path, so spill the upload to a temp file.
+        with tempfile.NamedTemporaryFile(suffix=".xlsx", delete=False) as tmp:
+            tmp.write(uploaded.getvalue())
+            xlsx_path = tmp.name
+        try:
+            data = extract_master_sheet(xlsx_path)
+            data = recompute(data)
+
+            # Merge any developer-supplied capacity overrides.
+            if solar_pv:
+                data.minigrid.solar_pv = solar_pv
+            if battery:
+                data.minigrid.battery_storage = battery
+            if annual_consumption:
+                data.minigrid.annual_consumption = annual_consumption
+
+            data = validate(data)
+
+            narrative_note = None
+            if want_narratives:
+                from pue_report_agent import generate_narratives
+                if generate_narratives is None:
+                    narrative_note = ("langchain isn't installed — prose "
+                                      "sections used the fallback.")
+                elif not has_key:
+                    narrative_note = ("No API key — prose sections used the "
+                                      "fallback.")
+                else:
+                    data = generate_narratives(data)
+
+            # Render to a temp .docx and read the bytes back for download.
+            from pue_report_agent.render import render
+            out_path = os.path.join(tempfile.gettempdir(),
+                                    "PUE_Report.docx")
+            render(data, out_path, developer=developer,
+                   report_date=report_date)
+            with open(out_path, "rb") as fh:
+                docx_bytes = fh.read()
+        finally:
+            try:
+                os.unlink(xlsx_path)
+            except OSError:
+                pass
+
+    st.success(f"Report generated for {data.community.name or 'the community'}.")
+    if narrative_note:
+        st.info(narrative_note)
+
+    fname = f"{(data.community.name or 'Community').replace(' ', '_')}_PUE_Report.docx"
+    st.download_button(
+        "⬇️ Download Word report", data=docx_bytes, file_name=fname,
+        mime="application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+        type="primary")
+
+    # Quick at-a-glance summary.
+    col1, col2, col3 = st.columns(3)
+    col1.metric("Interviewed", data.interviews.total)
+    col2.metric("Machines", len(data.processors.machinery))
+    col3.metric("Equipment cost (₦)",
+                f"{(data.budget.grand_total or 0):,.0f}")
+
+    if data.warnings:
+        with st.expander(f"⚠️ {len(data.warnings)} item(s) to review", expanded=True):
+            for w in data.warnings:
+                st.write("• " + w)
+    else:
+        st.caption("No validation warnings.")

pue_report_agent/__init__.py

@@ -0,0 +1,34 @@
+"""
+pue_report_agent
+================
+Turn a DREEF PUE master-sheet workbook into a community PUE report.
+
+Pipeline:
+    master.xlsx  ──extract──►  PUEReportData  ──validate──►  (+warnings)
+                                     │
+                                     ├──generate_narratives (LLM, prose only)
+                                     └──render (deterministic .docx)
+
+Public API:
+    extract_master_sheet(path)          -> PUEReportData      (no LLM)
+    validate(data)                      -> PUEReportData      (adds warnings)
+    generate_narratives(data, llm=None) -> PUEReportData      (LLM prose)
+    build_report_data(path, developer)  -> PUEReportData      (end-to-end)
+"""
+
+from .schema import PUEReportData
+from .extractors import extract_master_sheet
+from .validate import validate
+from .calc import recompute
+
+# agent imports langchain; keep it optional so extraction works without it.
+try:
+    from .agent import generate_narratives, build_report_data  # noqa: F401
+except ImportError:  # langchain not installed
+    generate_narratives = None  # type: ignore
+    build_report_data = None    # type: ignore
+
+__all__ = [
+    "PUEReportData", "extract_master_sheet", "validate", "recompute",
+    "generate_narratives", "build_report_data",
+]

pue_report_agent/agent.py

@@ -0,0 +1,184 @@
+"""
+agent.py
+========
+The LangChain layer. Two responsibilities, kept deliberately narrow:
+
+1.  **Narrative generation chains** — the only place an LLM is used. From the
+    review, the genuine value-add of AI is converting structured ESG / analysis
+    rows into the three prose passages a human would otherwise write by hand:
+    the Community Overview, the Demographic narrative, and the Processing
+    Insights. Everything else (tables, totals, boilerplate) is deterministic.
+
+2.  **Orchestration** — a small graph that runs extraction, fans out the
+    narrative chains, validates, and hands a fully-populated `PUEReportData` to
+    the document generator.
+
+Why constrain the LLM to prose only:
+  * Tables and budgets must reconcile to the spreadsheet to the naira. An LLM
+    re-typing numbers is how the Kwarua Tasha report ended up with figures that
+    didn't match its own master sheet. So numbers never pass through a prompt.
+  * Boilerplate is identical across reports; sending it to a model only adds
+    drift risk.
+
+The chains use LangChain Expression Language (LCEL). Swap `ChatAnthropic` for
+your provider of choice; the rest is provider-agnostic.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Optional
+
+from langchain_core.prompts import ChatPromptTemplate
+from langchain_core.output_parsers import StrOutputParser
+
+from .schema import PUEReportData
+from .extractors import extract_master_sheet
+
+
+# --------------------------------------------------------------------------- #
+# Models
+# --------------------------------------------------------------------------- #
+# All narrative prose is currently generated with Gemini. The model is
+# swappable per call — any LangChain BaseChatModel works — so we can move
+# individual chains to other providers later without touching the chains
+# themselves. The import is local so the package still loads (for
+# extraction/validation/render) when langchain-google-genai isn't installed.
+
+def _gemini(temperature: float = 0.2):
+    from langchain_google_genai import ChatGoogleGenerativeAI
+    return ChatGoogleGenerativeAI(model="gemini-1.5-pro",
+                                  temperature=temperature, max_output_tokens=1200)
+
+
+# Default model factory for every chain. Point this elsewhere to switch
+# providers globally.
+def _llm(temperature: float = 0.2):
+    return _gemini(temperature)
+
+
+# --------------------------------------------------------------------------- #
+# Shared system instruction — the guardrail against fabrication
+# --------------------------------------------------------------------------- #
+_SYSTEM = (
+    "You are a technical writer producing a Productive Use of Energy (PUE) "
+    "feasibility report for a rural Nigerian community. You write in formal, "
+    "neutral, third-person prose suitable for an investor-facing document. "
+    "Absolute rules:\n"
+    "1. Use ONLY the facts provided in the JSON. Never invent figures, names, "
+    "places, dates, or claims that are not present.\n"
+    "2. Do not output any number that is not in the JSON. If a number would "
+    "help but isn't supplied, write around it qualitatively.\n"
+    "3. No headings, bullet lists, or markdown — return clean paragraphs only.\n"
+    "4. If a field is empty, omit it gracefully rather than guessing."
+)
+
+
+# --------------------------------------------------------------------------- #
+# Chain 1 — Community Overview
+# --------------------------------------------------------------------------- #
+_overview_prompt = ChatPromptTemplate.from_messages([
+    ("system", _SYSTEM),
+    ("human",
+     "Write a 2–3 paragraph Community Overview for the project site. Cover "
+     "location and access, dominant and minority ethnic groups and languages, "
+     "the main livelihoods, governance/community structures, the current "
+     "electricity situation, and the community's stated attitude to the "
+     "project. Here is the data:\n\n```json\n{community_json}\n```"),
+])
+
+
+def _overview_chain(llm):
+    return _overview_prompt | llm | StrOutputParser()
+
+
+# --------------------------------------------------------------------------- #
+# Chain 2 — Demographic & Socio-Economic narrative
+# --------------------------------------------------------------------------- #
+_demographic_prompt = ChatPromptTemplate.from_messages([
+    ("system", _SYSTEM),
+    ("human",
+     "Write a 1–2 paragraph Demographic and Socio-Economic narrative that "
+     "introduces the table which will follow it. Summarise what most households "
+     "depend on, the dominant crops, the nature of agro-processing in the "
+     "community, and the SME and e-mobility activity levels. Use the interview "
+     "counts and crop/SME/mobility summaries provided. Data:\n\n"
+     "```json\n{summary_json}\n```"),
+])
+
+
+def _demographic_chain(llm):
+    return _demographic_prompt | llm | StrOutputParser()
+
+
+# --------------------------------------------------------------------------- #
+# Chain 3 — Processing Insights
+# --------------------------------------------------------------------------- #
+_processing_prompt = ChatPromptTemplate.from_messages([
+    ("system", _SYSTEM),
+    ("human",
+     "Write a short Processing Insights passage (2 paragraphs max) describing "
+     "the agro-processing landscape: which crops are processed, the dominant "
+     "business model (cash-for-service vs goods-for-service), the gender "
+     "composition of processors, and the contrast between peak-season and "
+     "scarce-season throughput. Be qualitative about volumes; the exact figures "
+     "appear in the adjacent tables. Data:\n\n```json\n{processors_json}\n```"),
+])
+
+
+def _processing_chain(llm):
+    return _processing_prompt | llm | StrOutputParser()
+
+
+# --------------------------------------------------------------------------- #
+# Orchestration
+# --------------------------------------------------------------------------- #
+def generate_narratives(data: PUEReportData,
+                        llm=None) -> PUEReportData:
+    """
+    Run the three prose chains and attach results to the data object.
+
+    All narratives currently use Gemini (gemini-1.5-pro). Pass `llm` to override
+    with any LangChain chat model.
+    """
+    llm = llm or _gemini()
+
+    community_json = data.community.model_dump_json(indent=2)
+
+    summary_payload = {
+        "interviews": data.interviews.model_dump(),
+        "farmers": {"male": data.farmers.male, "female": data.farmers.female,
+                    "crops": [c.model_dump() for c in data.farmers.crops]},
+        "sme": data.sme.model_dump(),
+        "mobility": data.mobility.model_dump(),
+        "key_agro_commodities": data.community.key_agro_commodities,
+    }
+    processors_json = data.processors.model_dump_json(indent=2)
+
+    data.narrative_overview = _overview_chain(llm).invoke(
+        {"community_json": community_json})
+    data.narrative_demographic = _demographic_chain(llm).invoke(
+        {"summary_json": json.dumps(summary_payload, indent=2)})
+    data.narrative_processing_insights = _processing_chain(llm).invoke(
+        {"processors_json": processors_json})
+    return data
+
+
+def build_report_data(master_sheet_path: str,
+                      developer: str = "the mini-grid developer",
+                      run_narratives: bool = True) -> PUEReportData:
+    """
+    End-to-end: master sheet -> validated, narrated PUEReportData.
+
+    Deterministic extraction first, LLM prose second. All narratives are
+    produced by Gemini. The document renderer (render.py) consumes the result.
+    `developer` is an external input that isn't in the sheet.
+    """
+    from .calc import recompute
+    from .validate import validate
+    data = extract_master_sheet(master_sheet_path)
+    data = recompute(data)
+    data = validate(data)
+    if run_narratives:
+        data = generate_narratives(data)
+    return data

pue_report_agent/calc.py

@@ -0,0 +1,168 @@
+"""
+calc.py
+=======
+Deterministic recomputation of every derived figure in the report.
+
+The agent must NEVER reproduce a wrong total. The source template shipped with a
+BOQ Grand Total of ₦30,756,000 when its own line items summed to ₦37,256,000
+(the Farming line had been dropped). A master sheet can carry the same kind of
+defect. So before rendering, the agent recomputes:
+
+* each budget section total   = Σ line-item total_price
+* the BOQ grand total         = Σ section totals
+* each equipment TOTAL row    = Σ power ratings (kW) and Σ quantities
+* each energy-projection total= Σ projection rows
+* each financial-model total  = Σ (amount_monthly × quantity)
+
+Recomputed values overwrite whatever was extracted, and any disagreement with
+the sheet's own stated total is recorded in `warnings` so a human sees that the
+source workbook didn't foot.
+"""
+
+from __future__ import annotations
+
+from .schema import PUEReportData, EquipmentPlan
+
+
+def recompute(data: PUEReportData) -> PUEReportData:
+    _budget(data)
+    _equipment(data.equipment_pilot, data)
+    _equipment(data.equipment_scaleup, data)
+    _energy_projection(data.equipment_pilot)
+    _energy_projection(data.equipment_scaleup)
+    _financials(data)
+    _co2(data)
+    return data
+
+
+# IPCC default emission factors (kg CO2 per litre of fuel).
+_CO2_FACTOR = {"Petrol": 2.31, "Diesel": 2.86}
+
+
+def _co2(data: PUEReportData) -> None:
+    """Compute per-machine CO2 = annual fuel litres x IPCC factor, where litres
+    are available. Rows without a litres input keep co2_kg = None (flagged in
+    validation); they don't contribute to the total."""
+    for row in data.processors.co2_assessment:
+        if row.annual_fuel_litres is not None:
+            factor = _CO2_FACTOR.get(row.fuel_type)
+            if factor is not None:
+                row.co2_kg = round(row.annual_fuel_litres * factor, 2)
+
+
+def _budget(data: PUEReportData) -> None:
+    grand = 0.0
+    for s in data.budget.sections:
+        line_sum = sum(i.total_price or 0 for i in s.items)
+        if s.items:
+            if s.total is not None and abs(line_sum - s.total) > 1:
+                data.warnings.append(
+                    f"Budget section '{s.name}': sheet stated "
+                    f"{s.total:,.0f} but line items sum to {line_sum:,.0f}. "
+                    f"Using the recomputed figure.")
+            s.total = line_sum
+        grand += s.total or 0
+    if data.budget.grand_total is not None and abs(grand - data.budget.grand_total) > 1:
+        data.warnings.append(
+            f"BOQ grand total: sheet stated {data.budget.grand_total:,.0f} but "
+            f"sections sum to {grand:,.0f}. Using the recomputed figure.")
+    data.budget.grand_total = grand
+
+
+def _equipment(plan: EquipmentPlan, data: PUEReportData) -> None:
+    """Add a recomputed TOTAL row to each equipment section.
+
+    The total power/energy is the sum of (per-unit rating x quantity), and it
+    lands in different columns depending on the table's layout:
+      * Power Rating + Quantity tables  -> the QUANTITY total holds
+        sum(power_rating x quantity); the Power Rating total is left blank.
+        (e.g. cassava: 5.5x1 + 4x1 = 9.5 shown under Quantity)
+      * Charging Rate + Quantity tables -> the CHARGING RATE total holds
+        sum(charging_rate x quantity); Quantity totals as a plain count.
+        (e.g. 4 two-wheelers x 1.35 = 5.4 shown under Charging Rate)
+    Charging-time totals are left blank. The farming/irrigation section is
+    exempt and keeps simple sums (its template row is placeholder zeros).
+    """
+    for sec in plan.sections:
+        if not sec.rows:
+            sec.total_row = []
+            continue
+        ncols = len(sec.headers) or max(len(r) for r in sec.rows)
+        headers = [str(h).lower() for h in (sec.headers or [])]
+
+        def _is(kind, ci):
+            return ci < len(headers) and kind in headers[ci]
+
+        qty_col = next((ci for ci in range(ncols) if _is("quantity", ci)
+                        or (ci < len(headers) and headers[ci].strip() == "qty")), None)
+        power_col = next((ci for ci in range(ncols)
+                          if _is("power rating", ci) or _is("rating (kw)", ci)), None)
+        charge_col = next((ci for ci in range(ncols)
+                           if _is("charging rate", ci)), None)
+        is_farming = ("farming" in (sec.name or "").lower() or
+                      any("irrigation" in str(r[0]).lower() for r in sec.rows if r))
+
+        def _sum_product(rate_col):
+            s, ok = 0.0, False
+            for r in sec.rows:
+                val = _to_num(r[rate_col]) if rate_col < len(r) else None
+                q = _to_num(r[qty_col]) if qty_col < len(r) else None
+                if val is not None and q is not None:
+                    s += val * q; ok = True
+            return (f"{s:g}" if ok else "")
+
+        total = ["" for _ in range(ncols)]
+        total[0] = "TOTAL"
+        for ci in range(1, ncols):
+            if _is("charging time", ci):
+                continue
+            if not is_farming and qty_col is not None:
+                # Quantity total = sum(power rating x qty) when a Power Rating
+                # column is present; otherwise a plain count.
+                if ci == qty_col and power_col is not None:
+                    total[ci] = _sum_product(power_col)
+                    continue
+                # Power Rating total stays blank (its product lives in Quantity).
+                if ci == power_col:
+                    continue
+                # Charging Rate total = sum(charging rate x qty).
+                if ci == charge_col:
+                    total[ci] = _sum_product(charge_col)
+                    continue
+            # Plain column sum (plain Quantity count, or any other numeric col).
+            col_vals, numeric = [], True
+            for r in sec.rows:
+                v = r[ci] if ci < len(r) else None
+                if v in (None, ""):
+                    continue
+                num = _to_num(v)
+                if num is None:
+                    numeric = False
+                    break
+                col_vals.append(num)
+            if numeric and col_vals:
+                total[ci] = f"{sum(col_vals):g}"
+        sec.total_row = total
+
+
+def _to_num(v):
+    if isinstance(v, (int, float)):
+        return float(v)
+    try:
+        return float(str(v).replace(",", "").strip())
+    except (ValueError, AttributeError):
+        return None
+
+
+def _energy_projection(plan: EquipmentPlan) -> None:
+    if not plan.projection:
+        return
+    total_kwh = sum(p.kwh for p in plan.projection)
+    total_six = sum(p.six_hour_day for p in plan.projection)
+    plan.projection_total_kwh = round(total_kwh, 2)
+    plan.projection_total_six_hour = round(total_six, 2)
+
+
+def _financials(data: PUEReportData) -> None:
+    for m in data.financial_models:
+        m.total_monthly = sum(r.amount_monthly * r.quantity for r in m.rows) or None

pue_report_agent/extractors.py

@@ -0,0 +1,1037 @@
+"""
+extractors.py
+=============
+Reads a PUE master-sheet workbook and returns a validated `PUEReportData`.
+
+Everything here is keyed to the *observed* layout of the DREEF master sheets
+(Jaji + Kwarua Tasha). The layout is irregular — analysis sheets are
+label/value blocks rather than tidy tables — so extraction is done with small
+"block readers" that locate a section by its label and walk down/right from it
+rather than by hardcoded cell addresses. That makes the agent resilient to rows
+being inserted above a block.
+
+Key resilience rules baked in (learned from the review):
+
+1.  **Raw/analysis sheets win over Key Findings.** Key Findings carries stale
+    template text from other communities (e.g. "Ondo", "Oil palm and Cassava").
+    Where both exist, we read the analysis sheet and only fall back to Key
+    Findings for developer-supplied figures (capacities, revenue-per-user,
+    impact) that aren't derivable from raw data.
+
+2.  **Template-pollution detection.** When a value matches a known stale
+    template string, we keep it but append a warning so a human reviews it.
+
+3.  **Community-name fuzziness.** The sheets spell the community several ways
+    ("Jaji"/"Jaiji", "Kwarau"/"Kwarua Tasha"). We normalise on read.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any, Optional
+
+from openpyxl import load_workbook
+from openpyxl.worksheet.worksheet import Worksheet
+
+from .schema import (
+    PUEReportData, CommunityProfile, EnergySystemSpec, DistributionLine,
+    InterviewCounts, FarmerAnalysis, CropRow, ProcessorAnalysis, MachineRow,
+    ProcessingQtyRow, BusinessModelRow, MobilityAnalysis, SMEAnalysis,
+    SMETypeRow, EquipmentPlan, EquipmentSection, EnergyProjectionRow, Budget,
+    BudgetSection, BudgetLineItem, FinancialModel, FinancialRow,
+    RevenuePerUserRow, ImpactRow, DistanceRow, CO2EmissionRow,
+)
+
+# Strings that, if found verbatim, mean someone forgot to update the template.
+STALE_TEMPLATE_MARKERS = [
+    "Oilpalm and Cassava", "Oil palm and Cassava", "Ondo",
+    "315.5 kWp",  # appears in both Key Findings tabs regardless of community
+    "34 male vs 7 female",
+]
+
+
+# --------------------------------------------------------------------------- #
+# Low-level grid helpers
+# --------------------------------------------------------------------------- #
+def _rows(ws: Worksheet) -> list[list[Any]]:
+    """Whole sheet as a list-of-lists, values only. Cheap enough for these."""
+    return [list(r) for r in ws.iter_rows(values_only=True)]
+
+
+def _norm(v: Any) -> str:
+    return ("" if v is None else str(v)).strip()
+
+
+def _num(v: Any) -> Optional[float]:
+    if v is None:
+        return None
+    if isinstance(v, (int, float)):
+        return float(v)
+    s = str(v).replace(",", "").replace("₦", "").replace("#", "").strip()
+    s = re.sub(r"[^\d.\-]", "", s)
+    try:
+        return float(s) if s not in ("", "-", ".") else None
+    except ValueError:
+        return None
+
+
+def _label_col(rows: list[list[Any]], label: str, start: int = 0,
+               exact: bool = False) -> tuple[int, int]:
+    """
+    Locate a label ANYWHERE in the grid. Returns (row_index, col_index) of the
+    matching cell, or (-1, -1). Master sheets often indent blocks into column B
+    (column A is a blank margin), so we cannot assume a fixed column.
+
+    `exact=True` requires the whole trimmed cell to equal the label, which
+    avoids 'Farmer' matching inside 'Farmers Analysis', etc.
+    """
+    needle = label.lower()
+    for i in range(start, len(rows)):
+        for c, cell in enumerate(rows[i]):
+            text = _norm(cell).lower()
+            if not text:
+                continue
+            if (text == needle) if exact else (needle in text):
+                return i, c
+    return -1, -1
+
+
+def _find_row(rows: list[list[Any]], label: str, col: int = 0,
+              start: int = 0) -> int:
+    """Row index of the first cell containing `label` (searches all columns)."""
+    i, _ = _label_col(rows, label, start=start)
+    return i
+
+
+def _value_to_right(rows: list[list[Any]], label: str,
+                    label_col: int = 0, exact: bool = False) -> Optional[Any]:
+    """First non-empty cell to the right of wherever `label` is found."""
+    i, c = _label_col(rows, label, exact=exact)
+    if i < 0:
+        return None
+    for cc in range(c + 1, len(rows[i])):
+        if _norm(rows[i][cc]):
+            return rows[i][cc]
+    return None
+
+
+def _cell(row: list[Any], idx: int) -> Any:
+    return row[idx] if 0 <= idx < len(row) else None
+
+
+def _table_under(rows: list[list[Any]], header_label: str, n_cols: int,
+                 start: int = 0) -> tuple[int, list[list[Any]]]:
+    """
+    Find a header by label; return (anchor_col, data_rows) with each row sliced
+    to `n_cols` columns starting at the header's column. Stops at the first row
+    whose anchor cell is blank. Handles the blank column-A margin used by these
+    sheets, where real content begins in column B.
+    """
+    i, c = _label_col(rows, header_label, start=start)
+    if i < 0:
+        return -1, []
+    out = []
+    for r in rows[i + 1:]:
+        if not _norm(_cell(r, c)):
+            break
+        out.append([_cell(r, c + k) for k in range(n_cols)])
+    return c, out
+
+
+# --------------------------------------------------------------------------- #
+# Section extractors
+# --------------------------------------------------------------------------- #
+def extract_community(wb, warnings: list[str]) -> CommunityProfile:
+    esg = _rows(wb["ESG"])
+    kf = _rows(wb["Key Findings"]) if "Key Findings" in wb.sheetnames else []
+
+    # ESG is a 2-row sheet: header row + single data row.
+    header = [_norm(c) for c in esg[0]]
+    data = esg[1] if len(esg) > 1 else []
+
+    def esg_get(col_contains: str) -> str:
+        for idx, h in enumerate(header):
+            if col_contains.lower() in h.lower():
+                return _norm(data[idx]) if idx < len(data) else ""
+        return ""
+
+    name = esg_get("Name of Community") or "Unknown"
+    name = re.sub(r"\bKwarau\b", "Kwarua", name).strip()
+
+    # Demographic block lives in Key Findings as label/detail pairs.
+    def kf_detail(label: str) -> str:
+        return _norm(_value_to_right(kf, label)) if kf else ""
+
+    # State sits below a "State" header in the KF top table (header/value layout).
+    state = ""
+    si, sc = _label_col(kf, "State", exact=True) if kf else (-1, -1)
+    if si >= 0 and si + 1 < len(kf):
+        state = _norm(_cell(kf[si + 1], sc))
+
+    profile = CommunityProfile(
+        name=name,
+        lga=esg_get("Local Government Area") or kf_detail("LGA"),
+        state=state,
+        latitude=_num(esg_get("latitude")) or 0.0,
+        longitude=_num(esg_get("longitude")) or 0.0,
+        topography_climate=kf_detail("Topography and Climate"),
+        land_use=kf_detail("Land Use"),
+        population_estimate=int(_num(kf_detail("Population Estimates")) or 0) or None,
+        households=int(_num(kf_detail("Number of Households")) or 0) or None,
+        major_ethnic_groups=kf_detail("Major Ethnic Groups")
+                            or esg_get("Dominant Tribe"),
+        languages_spoken=kf_detail("Languages Spoken"),
+        key_economic_activities=kf_detail("Key Economic Activities")
+                               or esg_get("primary economic activities"),
+        key_agro_commodities=kf_detail("Key Agro Commodities"),
+        processing_methods=kf_detail("Processing Methods"),
+        num_agro_processors=int(_num(kf_detail("Number of Agro-Processors")) or 0) or None,
+        farmers_cooperative=kf_detail("Farmers' Cooperative"),
+        infrastructure=kf_detail("Infrastructure"),
+        landmarks=esg_get("Major Landmarks"),
+        grid_status=esg_get("Nearest community with Grid"),
+        network_available=esg_get("Available Network"),
+        water_sources=esg_get("Sources of water"),
+        community_sentiment=esg_get("How does the community feel"),
+        land_ownership=esg_get("Who owns or occupies the land"),
+        community_structures=esg_get("existing community structures"),
+    )
+
+    # Security & Social Risks: compose a factual summary from the ESG risk
+    # questions (no invention — only what the respondent answered).
+    def _is_no(ans: str) -> bool:
+        return ans.strip().lower() in ("no", "none", "nil", "n")
+
+    def _is_yes(ans: str) -> bool:
+        return ans.strip().lower().startswith("yes")
+
+    sec = esg_get("victim of security issues")
+    land = esg_get("land disputes or boundary")
+    pol = esg_get("conflicting political actors")
+    clear, concerns = [], []
+    for label, ans in (("security incidents", sec),
+                       ("land or boundary disputes", land),
+                       ("political conflicts", pol)):
+        if not ans:
+            continue
+        (clear if _is_no(ans) else concerns).append(label)
+    parts = []
+    if clear:
+        parts.append("No reported " + ", ".join(clear) + ".")
+    if concerns:
+        parts.append("Reported concerns: " + ", ".join(concerns) + ".")
+    profile.security_social_risks = " ".join(parts)
+
+    # Flag stale template values pulled from Key Findings.
+    for field in ("key_agro_commodities", "state", "languages_spoken"):
+        val = getattr(profile, field)
+        if any(m.lower() in val.lower() for m in STALE_TEMPLATE_MARKERS):
+            warnings.append(
+                f"community.{field} = '{val}' matches a known template "
+                f"string and may be stale; verify against raw survey sheets."
+            )
+    return profile
+
+
+def extract_interviews(wb) -> InterviewCounts:
+    kf = _rows(wb["Key Findings"])
+    def g(lbl):  # noqa
+        return int(_num(_value_to_right(kf, lbl, exact=True)) or 0)
+    return InterviewCounts(
+        total=g("People interviewed"),
+        farmers=g("Farmer"),
+        agroprocessors=g("Agroprocessors"),
+        sme=g("SME"),
+        mobility=g("Mobility"),
+    )
+
+
+def extract_farmers(wb) -> FarmerAnalysis:
+    fa = _rows(wb["Farmers Analysis Sheet "]) if \
+        "Farmers Analysis Sheet " in wb.sheetnames else _rows(wb["Farmers Analysis Sheet"])
+    male = int(_num(_value_to_right(fa, "Male")) or 0)
+    female = int(_num(_value_to_right(fa, "Female")) or 0)
+
+    # Crop table: header row is "Crop | Farming household | % | ... | Area".
+    # Anchor on "Crop" so crop names (leftmost col) are captured.
+    kf = _rows(wb["Key Findings"])
+    crops: list[CropRow] = []
+    fh = _find_row(kf, "Farming household")
+    _, table = _table_under(kf, "Crop", n_cols=6, start=max(0, fh - 1))
+    for row in table:
+        crop = _norm(row[0])
+        if not crop or _num(row[1]) is None:
+            break
+        crops.append(CropRow(
+            crop=crop,
+            farming_households=int(_num(row[1]) or 0),
+            percentage=round(_num(row[2]) or 0, 1),
+            annual_production_interviewed=_num(row[3]) or 0,
+            estimated_annual_production_community=_num(row[4]) or 0,
+            total_area_planted_hectares=_num(row[5]) or 0,
+        ))
+    return FarmerAnalysis(male=male, female=female, crops=crops)
+
+
+def extract_processors(wb) -> ProcessorAnalysis:
+    pa = _rows(wb["Processors Analysis Sheet"])
+    male = int(_num(_value_to_right(pa, "Male")) or 0)
+    female = int(_num(_value_to_right(pa, "Female")) or 0)
+
+    # Processing quantity table: header "Crops Processed | Total Peak | Total
+    # Scarce | Avg Peak | Avg Scarce". Anchor on the metric header then step
+    # one column left to reach the crop names.
+    kf = _rows(wb["Key Findings"])
+    qty: list[ProcessingQtyRow] = []
+    qi, qc = _label_col(kf, "Total Quantity Processed (Peak)")
+    if qi >= 0:
+        crop_col = qc - 1
+        for r in kf[qi + 1:qi + 12]:
+            crop = _norm(_cell(r, crop_col))
+            if not crop or _num(_cell(r, qc)) is None:
+                break
+            qty.append(ProcessingQtyRow(
+                crop=crop,
+                total_peak=_num(_cell(r, qc)) or 0,
+                total_scarce=_num(_cell(r, qc + 1)) or 0,
+                avg_peak=_num(_cell(r, qc + 2)) or 0,
+                avg_scarce=_num(_cell(r, qc + 3)) or 0))
+
+    bms = _extract_business_models(kf)
+    # Machinery block sits AFTER the business-model table; scope the scan so the
+    # farmer crop table (which also contains "maize", "rice", ...) is excluded.
+    bm_row, _ = _label_col(kf, "cash as a service")
+    machines = _extract_machinery(kf, start=max(0, bm_row))
+    # Jaji-style grouped extraction is crop-group-keyed; communities like Abigi
+    # store machinery as a flat Machine/Specification/Quantity table with no
+    # group column, so fall back to a flat reader when nothing was found.
+    if not machines:
+        machines = _extract_machinery_flat(kf)
+
+    # Peak/scarce quantities: Jaji keeps them in Key Findings as a single table;
+    # Abigi keeps them in the Processors Analysis Sheet as four labelled blocks.
+    if not qty:
+        qty = _processing_qty_from_analysis(wb)
+
+    co2 = _co2_from_machinery(machines)
+
+    return ProcessorAnalysis(male=male, female=female,
+                             business_models=bms, machinery=machines,
+                             processing_quantities=qty, co2_assessment=co2)
+
+
+def _processing_qty_from_analysis(wb) -> list[ProcessingQtyRow]:
+    """Fallback peak/scarce reader for sheets (e.g. Abigi) that store the four
+    metrics in the Processors Analysis Sheet as labelled blocks:
+
+        Total Quantity Processed (Peak) | Cassava | 960
+                                        | Oil Palm | 96
+        Average Quantity (Peak)         | Cassava | 240
+        ...
+    """
+    if "Processors Analysis Sheet" not in wb.sheetnames:
+        return []
+    pa = _rows(wb["Processors Analysis Sheet"])
+    metrics = [("Total Quantity Processed (Peak)", "total_peak"),
+               ("Average Quantity (Peak)", "avg_peak"),
+               ("Total Quantity Processed (Scarce)", "total_scarce"),
+               ("Average Quantity Processed (Scarce)", "avg_scarce")]
+    data: dict = {}
+    order: list = []
+    for label, field in metrics:
+        i, c = _label_col(pa, label)
+        if i < 0:
+            continue
+        for k in range(i, min(i + 12, len(pa))):
+            crop = _norm(_cell(pa[k], c + 1))
+            val = _num(_cell(pa[k], c + 2))
+            # A new metric label in column c ends this block.
+            other = _norm(_cell(pa[k], c))
+            if k > i and other and _num(other) is None:
+                break
+            if not crop or val is None:
+                if k > i:
+                    break
+                continue
+            key = crop.strip().lower()
+            if key not in data:
+                data[key] = {"crop": crop.strip()}
+                order.append(key)
+            data[key][field] = val
+    return [ProcessingQtyRow(
+                crop=data[k]["crop"],
+                total_peak=data[k].get("total_peak", 0),
+                total_scarce=data[k].get("total_scarce", 0),
+                avg_peak=data[k].get("avg_peak", 0),
+                avg_scarce=data[k].get("avg_scarce", 0)) for k in order]
+
+
+def _co2_from_machinery(machines) -> list[CO2EmissionRow]:
+    """Build CO2-assessment rows for the fuel-powered machines (Petrol/Diesel)
+    found in the machinery list. Per-machine annual fuel consumption is not in
+    the master sheets, so annual_fuel_litres/co2_kg are left None here and the
+    figures are computed in calc.recompute() once litres are supplied; validate
+    flags the missing input.
+    """
+    out: list[CO2EmissionRow] = []
+    for m in machines:
+        if m.power_source in ("Petrol", "Diesel"):
+            out.append(CO2EmissionRow(
+                machine=m.machine,
+                specification=m.rated_power,
+                fuel_type=m.power_source,
+                num_machines=m.count))
+    return out
+
+
+def _extract_business_models(kf) -> list[BusinessModelRow]:
+    # Header row is "Crops Processed | Male | Female | cash as a service | ...".
+    out: list[BusinessModelRow] = []
+    _, table = _table_under(kf, "Crops Processed", n_cols=6)
+    for row in table:
+        crop = _norm(row[0])
+        if not crop or _num(row[1]) is None:
+            break
+        out.append(BusinessModelRow(
+            crop=crop, male=int(_num(row[1]) or 0), female=int(_num(row[2]) or 0),
+            cash_as_service=int(_num(row[3]) or 0),
+            goods_as_service=int(_num(row[4]) or 0),
+            purchase_raw_materials=int(_num(row[5]) or 0)))
+    return out
+
+
+_FUEL_SOURCES = (("diesel", "Diesel"), ("petrol", "Petrol"),
+                 ("electric", "Electric"), ("solar", "Solar"),
+                 ("manual", "Manual"))
+_FUEL_EMISSION_KG_PER_L = {"Petrol": 2.31, "Diesel": 2.86}  # IPCC factors
+
+
+def _parse_machine_spec(spec: str) -> tuple:
+    """Split a free-text machine specification into (power_source, rated_power).
+
+    Sheets vary: Jaji writes "15 HP electric motor machine" (rating + source in
+    one string); Abigi's flat table puts EITHER a rating ("13hp", "6.5 hp") OR a
+    source ("Petrol", "Manual") in the cell. We pull whatever is present; either
+    field may come back empty.
+    """
+    s = (spec or "").strip()
+    low = s.lower()
+    source = ""
+    for kw, label in _FUEL_SOURCES:
+        if kw in low:
+            source = label
+            break
+    if source:
+        # Rating + source share one string (e.g. "15 HP electric motor"):
+        # pull just the rating out.
+        m = re.search(r"\d+(?:\s*\.\s*\d+)?\s*(?:hp|horse\s*power)", low)
+        rated = s[m.start():m.end()].strip() if m else ""
+    else:
+        # No fuel keyword: the whole cell is the rating (e.g. "6 .5 hp",
+        # "13hp", "20 horse power") — keep it intact rather than risk a partial
+        # regex match on malformed text.
+        rated = s if any(ch.isdigit() for ch in s) else ""
+    return source, rated
+
+
+def _mk_machine(crop_group: str, machine: str, spec: str,
+                count: int) -> MachineRow:
+    source, rated = _parse_machine_spec(spec)
+    return MachineRow(crop_group=crop_group, machine=machine,
+                      specification=spec, count=count,
+                      power_source=source, rated_power=rated)
+
+
+def _extract_machinery(kf, start: int = 0) -> list[MachineRow]:
+    """
+    Machinery rows sit under crop-group headers where the group name shares the
+    row of the first machine, e.g.:
+        | maize | Chaf remover | 15 horse power | 3 |
+        |       | Chaf remover | 20 horse power | 1 |
+    Group is in column B; machine/spec/count in C/D/E. `start` scopes the scan
+    past the farmer crop table, which also contains crop-group words.
+    """
+    out: list[MachineRow] = []
+    groups = {"maize", "rice", "sawmill", "saw mill", "multiple grains"}
+    current, in_block = "", False
+    _, anchor = _label_col(kf, "Crops Processed")
+    if anchor < 0:
+        anchor = 1
+    for r in kf[start:]:
+        g = _norm(_cell(r, anchor)).lower()
+        machine = _norm(_cell(r, anchor + 1))
+        spec = _norm(_cell(r, anchor + 2))
+        cnt = _num(_cell(r, anchor + 3))
+        # A genuine machine name is non-numeric. Numeric "machine" cells are
+        # bleed-through from the business-model and quantity tables.
+        machine_is_real = bool(machine) and _num(machine) is None
+        if g in groups and machine_is_real:
+            current, in_block = _norm(_cell(r, anchor)), True
+            if cnt is not None:
+                out.append(_mk_machine(current, machine, spec, int(cnt)))
+        elif in_block and not g and machine_is_real:
+            if cnt is not None:
+                out.append(_mk_machine(current, machine, spec, int(cnt)))
+        elif in_block and g and g not in groups:
+            in_block = False
+    return out
+
+
+def _extract_machinery_flat(kf) -> list[MachineRow]:
+    """Fallback for sheets whose machinery is a flat table with no crop-group
+    column, e.g. Abigi's Key Findings:
+
+        | Machine | Specification | Quantity |
+        | Digester | 6.5 hp | 1 |
+        | Grater   | 13hp    | 2 |
+
+    Located by a header row containing 'Machine' and 'Quantity'. Rows are read
+    until a blank/zero-padding row. crop_group is left generic because this
+    layout does not tie a machine to a specific crop.
+    """
+    out: list[MachineRow] = []
+    header_i = header_c = -1
+    for i, row in enumerate(kf):
+        cells = [_norm(x).lower() for x in row]
+        if any(x == "machine" for x in cells) and \
+           any("quantity" in x or x == "qty" for x in cells):
+            header_i = i
+            header_c = next(j for j, x in enumerate(cells) if x == "machine")
+            break
+    if header_i < 0:
+        return out
+    for r in kf[header_i + 1:header_i + 30]:
+        machine = _norm(_cell(r, header_c))
+        spec = _norm(_cell(r, header_c + 1))
+        cnt = _num(_cell(r, header_c + 2))
+        # Stop at blank or numeric-named padding rows (Abigi pads with "0|0|0").
+        if not machine or _num(machine) is not None:
+            break
+        if cnt is None or int(cnt) == 0:
+            continue
+        out.append(_mk_machine("processing equipment", machine, spec, int(cnt)))
+    return out
+
+
+def extract_mobility(wb) -> MobilityAnalysis:
+    name = ("E-Mobility Analysis Sheet " if "E-Mobility Analysis Sheet " in
+            wb.sheetnames else "E-Mobility Analysis Sheet")
+    ma = _rows(wb[name])
+
+    def block_total(label):
+        """A '... Revenue/Expenses/Profit' block lists Total then Average."""
+        i, c = _label_col(ma, label)
+        if i < 0:
+            return None
+        for r in ma[i:i + 3]:
+            if "total" in [_norm(x).lower() for x in r]:
+                nums = [_num(x) for x in r if _num(x) is not None]
+                return nums[0] if nums else None
+        return None
+
+    def block_avg(label):
+        """The 'Average' row sits just under the 'Total' row in each block."""
+        i, c = _label_col(ma, label)
+        if i < 0:
+            return None
+        for r in ma[i:i + 3]:
+            if "average" in [_norm(x).lower() for x in r]:
+                nums = [_num(x) for x in r if _num(x) is not None]
+                return nums[0] if nums else None
+        return None
+
+    kf = _rows(wb["Key Findings"])
+    return MobilityAnalysis(
+        total=int(_num(_value_to_right(kf, "E-Mobility", exact=True)) or 0),
+        okada=int(_num(_value_to_right(kf, "Okada", exact=True)) or 0),
+        tricycle=int(_num(_value_to_right(kf, "Tricycle", exact=True)) or 0),
+        boat=int(_num(_value_to_right(kf, "Boat", exact=True)) or 0),
+        daily_revenue_total=block_total("Daily Revenue"),
+        daily_revenue_avg=block_avg("Daily Revenue"),
+        daily_fuel_expense_total=block_total("Daily Expenses (Fuel)"),
+        daily_fuel_expense_avg=block_avg("Daily Expenses (Fuel)"),
+        daily_profit_total=block_total("Daily Profit"),
+        daily_profit_avg=block_avg("Daily Profit"),
+    )
+
+
+def extract_sme(wb) -> SMEAnalysis:
+    kf = _rows(wb["Key Findings"])
+    # Only used to LOCATE the block (the SME cell whose next row is a business
+    # type). We accept both Jaji's misspellings and the correct spellings so the
+    # locator works across sheets; row capture below does NOT depend on this set,
+    # so a community with new/relabelled SME types still extracts fully.
+    known = {"barbershop", "cold storage/ice block making", "grocery retail",
+             "phone charging", "phone repair", "cain production",
+             "cane production", "hairdressing", "welding", "printing/cybercafé",
+             "carpentary", "carpentry", "tailoring/fashion", "others"}
+    types: list[SMETypeRow] = []
+    total = 0
+    start = 0
+    while True:
+        i, c = _label_col(kf, "SME", start=start, exact=True)
+        if i < 0:
+            break
+        nxt = _norm(_cell(kf[i + 1], c)) if i + 1 < len(kf) else ""
+        if nxt.lower() in known:
+            total = int(_num(_cell(kf[i], c + 1)) or 0)
+            # Read every contiguous (label, count) row until the block ends.
+            # A row belongs to the block when its label cell is non-empty,
+            # non-numeric text and the cell to its right is a number. This is
+            # spelling-agnostic, so correctly-spelled "Cane Production" /
+            # "Carpentry" (Abigi) no longer terminate the scan early.
+            for r in kf[i + 1:i + 20]:
+                label = _norm(_cell(r, c))
+                cnt = _num(_cell(r, c + 1))
+                if label and _num(label) is None and cnt is not None:
+                    types.append(SMETypeRow(
+                        business_type=label, count=int(cnt)))
+                elif types:
+                    break
+            break
+        start = i + 1
+    return SMEAnalysis(total=total, types=types)
+
+
+_EQUIP_HEADER_TOKENS = ("capacity", "power", "quantity", "energy source",
+                        "charging rate", "charging time", "machine", "vehicles",
+                        "rating", "unit")
+
+
+def _is_equip_header(row) -> bool:
+    cells = [_norm(c).lower() for c in row if _norm(c)]
+    hits = sum(1 for c in cells
+               if any(tok in c for tok in _EQUIP_HEADER_TOKENS))
+    return hits >= 2
+
+
+def extract_equipment(wb, sheet_name: str, phase: str) -> EquipmentPlan:
+    rows = _rows(wb[sheet_name])
+    plan = EquipmentPlan(phase=phase)
+
+    pending_label = ""        # nearest single-cell label above a header row
+    i = 0
+    n = len(rows)
+    while i < n:
+        r = rows[i]
+        nonempty = [(ci, _norm(c)) for ci, c in enumerate(r) if _norm(c)]
+
+        # Stop scanning sections once we reach the energy-projection block.
+        if any("energy projection" in t.lower() for _, t in nonempty):
+            break
+
+        if not nonempty:
+            i += 1
+            continue
+
+        if _is_equip_header(r):
+            anchor = nonempty[0][0]
+            last_col = nonempty[-1][0]
+            width = last_col - anchor + 1
+            headers = [_norm(_cell(r, anchor + k)) for k in range(width)]
+            section = EquipmentSection(
+                name=pending_label or "Equipment", headers=headers)
+            j = i + 1
+            while j < n:
+                rr = rows[j]
+                first = _norm(_cell(rr, anchor))
+                low = first.lower()
+                if not first:
+                    break
+                if _is_equip_header(rr):
+                    break
+                if "energy projection" in " ".join(
+                        _norm(c).lower() for c in rr):
+                    break
+                if low in ("total", "total cost"):
+                    j += 1
+                    break          # recomputed by calc; don't store sheet total
+                section.rows.append(
+                    [_cell(rr, anchor + k) for k in range(width)])
+                j += 1
+            if section.rows:
+                plan.sections.append(section)
+            pending_label = ""
+            i = j
+            continue
+
+        # A single-content row is a candidate section label.
+        if len(nonempty) == 1 and _num(nonempty[0][1]) is None:
+            pending_label = nonempty[0][1]
+        i += 1
+
+    # Energy projection block (kW/hr and 6-hour-day columns).
+    pi, pc = _label_col(rows, "TOTAL ENERGY PROJECTION")
+    if pi >= 0:
+        for rr in rows[pi + 2:pi + 14]:
+            item = _norm(_cell(rr, pc))
+            if not item:
+                break
+            kwh = _num(_cell(rr, pc + 1))
+            six = _num(_cell(rr, pc + 2))
+            if item.upper() == "TOTAL":
+                plan.projection_total_kwh = kwh
+                plan.projection_total_six_hour = six
+                break
+            if kwh is None:
+                continue
+            plan.projection.append(EnergyProjectionRow(
+                item=item, kwh=kwh or 0, six_hour_day=six or 0))
+    return plan
+
+
+def extract_energy_systems(wb, warnings) -> tuple:
+    """Pull mini-grid and micro stand-alone capacities + distribution metrics
+    from Key Findings. These are developer-supplied figures that nonetheless
+    live in the sheet; extracting them avoids '[to be supplied]' gaps."""
+    kf = _rows(wb["Key Findings"])
+
+    def parse_block(start_label: str, stop_labels: list[str]) -> EnergySystemSpec:
+        i, _ = _label_col(kf, start_label)
+        spec = EnergySystemSpec()
+        if i < 0:
+            return spec
+        # scan a window after the label for the capacity lines + distribution
+        end = len(kf)
+        for k in range(i + 1, len(kf)):
+            line = " ".join(_norm(c) for c in kf[k])
+            if any(s.lower() in line.lower() for s in stop_labels):
+                end = k
+                break
+        in_dist = False
+        for k in range(i, end):
+            line = " ".join(_norm(c) for c in kf[k] if _norm(c)).strip()
+            low = line.lower()
+            if not line:
+                continue
+            if "solar pv" in low:
+                spec.solar_pv = line.split(":", 1)[-1].strip()
+            elif "inverter" in low:
+                spec.inverter = line.split(":", 1)[-1].strip()
+            elif "battery storage" in low:
+                spec.battery_storage = line.split(":", 1)[-1].strip()
+            elif "annual consumption" in low:
+                spec.annual_consumption = line.split(":", 1)[-1].strip()
+            elif "distribution metrics" in low or "target end users" in low:
+                in_dist = True
+            elif in_dist and "(" in line and ")" in line and \
+                    any(ch.isdigit() for ch in line[line.find("("):line.find(")")]):
+                # e.g. "Residential (90.34%): Households..." or "Public (1.75):"
+                name = line.split("(", 1)[0]
+                name = re.sub(r"^[\s·•\-\u00a0]+", "", name).strip()
+                pct = line[line.find("(") + 1:line.find(")")].strip()
+                if pct and not pct.endswith("%"):
+                    pct = pct + "%"
+                desc = line.split(":", 1)[-1].strip() if ":" in line else ""
+                if name:
+                    spec.distribution_metrics.append(DistributionLine(
+                        end_user=name, percentage=pct, description=desc))
+        spec.developer_supplied = True
+        if any(m.lower() in (spec.solar_pv + spec.battery_storage).lower()
+               for m in STALE_TEMPLATE_MARKERS):
+            spec.needs_review = True
+        return spec
+
+    # NB: the sheet's headings are the anchors, not the report's. This workbook
+    # labels the blocks "Mini-Grid Development Project" and "Micro Stand-Alone
+    # Energy System..." (hyphenated). Earlier versions looked for "Proposed
+    # Capacity"/"Micro Stand Alone" which don't appear in the sheet, so both
+    # blocks came back empty and rendered as "[to be supplied]".
+    minigrid = parse_block("Mini-Grid Development Project",
+                           ["Micro Stand-Alone", "Micro Stand Alone",
+                            "Energy Substitution", "Distance from"])
+    micro = parse_block("Micro Stand-Alone Energy System",
+                        ["Energy Substitution", "Distance from",
+                         "Name of SME", "Name of Processor"])
+    # Flag the known stale micro-distribution text without altering it.
+    for d in micro.distribution_metrics:
+        if any(m.lower() in d.description.lower() for m in STALE_TEMPLATE_MARKERS):
+            warnings.append(
+                f"Micro distribution metric '{d.end_user}' description "
+                f"('{d.description[:40]}...') matches stale template text; "
+                f"verify it reflects this community.")
+    return minigrid, micro
+
+
+def extract_budget(wb) -> Budget:
+    rows = _rows(wb["Budget"])
+    budget = Budget()
+    section_names = {"energy infrastructure", "energy", "energy box",
+                     "agricultural hub", "agrohub", "sunbread", "farming",
+                     "swap station", "mobility", "sme", "others"}
+
+    def map_columns(header_row: list[Any]) -> Optional[dict]:
+        """Map item/details/qty/unit/total to column indices from a header row.
+
+        Sections vary: the standard block is Item|Details|Quantity|Unit Price|
+        Total Price, but e.g. OTHERS is S/N|cat|Item|Qty|Unit Cost|Total. We
+        locate each field by its header text so offsets don't matter."""
+        cols = {}
+        for ci, cell in enumerate(header_row):
+            t = _norm(cell).lower()
+            if not t:
+                continue
+            if t in ("item", "machine") and "item" not in cols:
+                cols["item"] = ci
+            elif t in ("details", "specification", "spec", "capacity"):
+                cols.setdefault("details", ci)
+            elif t.startswith("qty") or t.startswith("quantity"):
+                cols["qty"] = ci
+            elif "unit" in t:
+                cols["unit"] = ci
+            elif t.startswith("total"):
+                cols["total"] = ci
+        # Some sections name the first column differently (e.g. "E-Mobility
+        # Vehicles"). If no explicit item header was found, use the first
+        # non-empty header cell as the item column.
+        if "item" not in cols:
+            for ci, cell in enumerate(header_row):
+                if _norm(cell):
+                    cols["item"] = ci
+                    break
+        return cols if "item" in cols and "total" in cols else None
+
+    i = 0
+    while i < len(rows):
+        # find a section header
+        label = next((_norm(c) for c in rows[i] if _norm(c)), "")
+        if label.lower() in section_names:
+            section = BudgetSection(name=label)
+            budget.sections.append(section)
+            # the header row is the next non-empty row
+            j = i + 1
+            cols = None
+            while j < len(rows):
+                if any(_norm(c) for c in rows[j]):
+                    cols = map_columns(rows[j])
+                    j += 1
+                    break
+                j += 1
+            if not cols:
+                i = j
+                continue
+            # read line items until a TOTAL row or blank/new-section row
+            while j < len(rows):
+                r = rows[j]
+                item = _norm(_cell(r, cols["item"]))
+                low = item.lower()
+                row_labels = [_norm(c).lower() for c in r]
+                if not item:
+                    break
+                if low in section_names:
+                    break
+                # TOTAL may sit in any column (e.g. OTHERS puts it in the
+                # category column, not the item column).
+                if low in ("total", "total cost") or \
+                        "total" in row_labels or "total cost" in row_labels:
+                    section.total = _num(_cell(r, cols["total"]))
+                    j += 1
+                    break
+                # If a non-empty, non-numeric category sits immediately left of
+                # the item column (as in the OTHERS block), prepend it so rows
+                # aren't all identically named ("Transportation & Logistics").
+                label = item
+                if cols["item"] > 0:
+                    left = _norm(_cell(r, cols["item"] - 1))
+                    if left and left != "0" and _num(left) is None \
+                            and left.lower() not in ("item", "s/n", "machine"):
+                        label = f"{left} \u2014 {item}"
+                section.items.append(BudgetLineItem(
+                    section=section.name, item=label,
+                    details=_norm(_cell(r, cols.get("details", -1)))
+                            if "details" in cols else "",
+                    quantity=_num(_cell(r, cols.get("qty", -1)))
+                             if "qty" in cols else None,
+                    unit_price=_num(_cell(r, cols.get("unit", -1)))
+                               if "unit" in cols else None,
+                    total_price=_num(_cell(r, cols["total"]))))
+                j += 1
+            i = j
+        else:
+            i += 1
+
+    budget.grand_total = sum(s.total for s in budget.sections if s.total) or None
+    return budget
+
+
+def extract_financials(wb) -> list[FinancialModel]:
+    rows = _rows(wb["Summary"])
+    models: list[FinancialModel] = []
+    current: Optional[FinancialModel] = None
+    model_names = {"individual model - new equipment",
+                   "individual model - retrofit", "agrohub model"}
+    # model name and beneficiary live in adjacent columns; find the model column
+    _, mcol = _label_col(rows, "Business Model")
+    if mcol < 0:
+        mcol = 1
+    bcol = mcol + 1
+    for r in rows:
+        name_cell = _norm(_cell(r, mcol)).strip()
+        if name_cell.lower() in model_names:
+            current = FinancialModel(model_name=name_cell)
+            models.append(current)
+            _append_fin_row(current, r, _norm(_cell(r, bcol)), bcol)
+            continue
+        if current is None:
+            continue
+        _append_fin_row(current, r, _norm(_cell(r, bcol)), bcol)
+    for m in models:
+        m.total_monthly = sum(x.amount_monthly * x.quantity for x in m.rows) or None
+    return models
+
+
+def _append_fin_row(model: FinancialModel, r, beneficiary, bcol):
+    if not beneficiary:
+        return
+    qty = _num(_cell(r, bcol + 1))
+    tf = _num(_cell(r, bcol + 2))
+    amt = _num(_cell(r, bcol + 3))
+    if amt is None:           # skip #DIV/0! rows (e.g. Farming with qty 0)
+        return
+    model.rows.append(FinancialRow(
+        beneficiary=beneficiary, quantity=qty or 0,
+        timeframe_months=tf or 0, amount_monthly=amt))
+
+
+def extract_revenue_per_user(wb, warnings) -> list[RevenuePerUserRow]:
+    kf = _rows(wb["Key Findings"])
+    i, c = _label_col(kf, "Effective Daily Demand")
+    out: list[RevenuePerUserRow] = []
+    if i < 0:
+        return out
+    cat_col = c - 1 if c > 0 else 0
+    for r in kf[i + 1:i + 8]:
+        cat = _norm(_cell(r, cat_col))
+        if not cat:
+            break
+        out.append(RevenuePerUserRow(
+            category=cat,
+            effective_daily_demand_kwh=_num(_cell(r, cat_col + 1)) or 0,
+            effective_annual_demand_kwh=_num(_cell(r, cat_col + 2)) or 0,
+            beneficiaries=int(_num(_cell(r, cat_col + 3)) or 0),
+            avg_tariff=_num(_cell(r, cat_col + 4)) or 0,
+            daily_revenue_category=_num(_cell(r, cat_col + 5)) or 0,
+            daily_avg_revenue=_num(_cell(r, cat_col + 6)) or 0))
+    if out:
+        warnings.append(
+            "revenue_per_user is developer-supplied and is frequently shared "
+            "across multiple communities. Confirm beneficiary counts and the "
+            "header label match THIS site before publishing.")
+    return out
+
+
+def extract_impact(wb) -> list[ImpactRow]:
+    kf = _rows(wb["Key Findings"])
+    _, table = _table_under(kf, "Impact Area", n_cols=3)
+    out: list[ImpactRow] = []
+    for row in table:
+        area = _norm(row[0])
+        if not area:
+            break
+        out.append(ImpactRow(impact_area=area, metric=_norm(row[1]),
+                             projected_outcome=_norm(row[2])))
+    return out
+
+
+def extract_distances(wb, community=None) -> list[DistanceRow]:
+    kf = _rows(wb["Key Findings"])
+    _, table = _table_under(kf, "Name of Processor", n_cols=4)
+    out: list[DistanceRow] = []
+    for row in table:
+        name = _norm(row[0])
+        if not name:
+            break
+        parts = _norm(row[1]).split()
+        out.append(DistanceRow(
+            name=name,
+            site_lat=_num(parts[0]) if parts else None,
+            site_long=_num(parts[1]) if len(parts) > 1 else None,
+            minigrid_gps=_norm(row[2]),
+            distance_km=_num(row[3])))
+    # Fallback (e.g. Abigi): no precomputed distance table in Key Findings.
+    # The Processors sheet carries a Name column and a GPS cell whose first two
+    # numbers are the site coordinates; the mini-grid reference point is the
+    # community centre, so distances are computed by haversine.
+    if not out and community is not None:
+        out = _distances_from_processors(wb, community)
+    return out
+
+
+def _haversine_km(lat1, lon1, lat2, lon2) -> float:
+    import math
+    r = 6371.0088
+    p1, p2 = math.radians(lat1), math.radians(lat2)
+    dp = math.radians(lat2 - lat1)
+    dl = math.radians(lon2 - lon1)
+    a = math.sin(dp / 2) ** 2 + math.cos(p1) * math.cos(p2) * math.sin(dl / 2) ** 2
+    return 2 * r * math.asin(math.sqrt(a))
+
+
+def _distances_from_processors(wb, community) -> list[DistanceRow]:
+    if "Processors" not in wb.sheetnames:
+        return []
+    rows = _rows(wb["Processors"])
+    # Locate the Name and GPS columns from the header row.
+    name_c = gps_c = -1
+    for hdr in rows[:3]:
+        for j, cell in enumerate(hdr):
+            t = _norm(cell).lower()
+            if t == "name":
+                name_c = j
+            elif t == "gps":
+                gps_c = j
+        if name_c >= 0 and gps_c >= 0:
+            break
+    if name_c < 0 or gps_c < 0:
+        return []
+    # Community centre = mini-grid reference. KF stores it as (x=6.49, y=4.39);
+    # the GPS cells use the same x/y order, so we stay internally consistent.
+    mg_x, mg_y = community.latitude, community.longitude
+    if not (mg_x and mg_y):
+        return []
+    out: list[DistanceRow] = []
+    for r in rows[1:]:
+        name = _norm(_cell(r, name_c))
+        gps = _norm(_cell(r, gps_c))
+        if not name or name.lower() == "name" or not gps:
+            continue
+        nums = [_num(x) for x in gps.replace(",", " ").split() if _num(x) is not None]
+        if len(nums) < 2:
+            continue
+        sx, sy = nums[0], nums[1]
+        dist = _haversine_km(sy, sx, mg_y, mg_x)
+        out.append(DistanceRow(
+            name=name, site_lat=sy, site_long=sx,
+            minigrid_gps=f"{mg_x}, {mg_y}", distance_km=round(dist, 3)))
+    return out
+
+
+# --------------------------------------------------------------------------- #
+# Public entry point
+# --------------------------------------------------------------------------- #
+def extract_master_sheet(path: str) -> PUEReportData:
+    wb = load_workbook(path, read_only=True, data_only=True)
+    warnings: list[str] = []
+
+    minigrid, micro = extract_energy_systems(wb, warnings)
+    community = extract_community(wb, warnings)
+    data = PUEReportData(
+        community=community,
+        minigrid=minigrid,
+        microgrid=micro,
+        interviews=extract_interviews(wb),
+        farmers=extract_farmers(wb),
+        processors=extract_processors(wb),
+        mobility=extract_mobility(wb),
+        sme=extract_sme(wb),
+        equipment_pilot=extract_equipment(wb, "Proposed Pilot PUE Equipment", "Pilot"),
+        equipment_scaleup=extract_equipment(wb, "Proposed ScaleUp PUE Equipment ", "ScaleUp"),
+        budget=extract_budget(wb),
+        financial_models=extract_financials(wb),
+        revenue_per_user=extract_revenue_per_user(wb, warnings),
+        projected_impact=extract_impact(wb),
+        processor_distances=extract_distances(wb, community),
+        warnings=warnings,
+    )
+    wb.close()
+    return data

pue_report_agent/fallback_narrative.py

@@ -0,0 +1,123 @@
+"""
+fallback_narrative.py
+======================
+Deterministic prose composed straight from the extracted data, used to fill the
+three narrative slots when the LLM (Gemini) hasn't been run — so the report is
+always complete and readable, never showing a "[narrative pending]" placeholder.
+
+These are plain factual sentences built from fields that are already in the
+schema; no numbers are invented. When `generate_narratives()` runs, its output
+overrides these.
+"""
+
+from __future__ import annotations
+
+from .schema import PUEReportData
+
+
+def _join(items: list[str]) -> str:
+    items = [i for i in items if i]
+    if not items:
+        return ""
+    if len(items) == 1:
+        return items[0]
+    return ", ".join(items[:-1]) + " and " + items[-1]
+
+
+def community_overview(data: PUEReportData) -> str:
+    c = data.community
+    bits = []
+    loc = f"{c.name} is a community in {c.lga}" + (f", {c.state} State" if c.state else "") + "."
+    bits.append(loc)
+    if c.latitude and c.longitude:
+        bits.append(f"It is located at approximately {c.latitude}, {c.longitude}.")
+    if c.topography_climate:
+        bits.append(f"The area lies within a {c.topography_climate.rstrip('.').lower()}.")
+    para1 = " ".join(bits)
+
+    bits2 = []
+    if c.major_ethnic_groups:
+        bits2.append(f"The population is made up of {c.major_ethnic_groups.rstrip('.').lower()}.")
+    if c.languages_spoken:
+        bits2.append(f"Languages spoken include {c.languages_spoken.rstrip('.').lower()}.")
+    if c.key_economic_activities:
+        bits2.append(f"The main economic activities are {c.key_economic_activities.rstrip('.').lower()}.")
+    if c.population_estimate:
+        hh = f" across roughly {c.households:,} households" if c.households else ""
+        bits2.append(f"The community has an estimated population of {c.population_estimate:,}{hh}.")
+    para2 = " ".join(bits2)
+
+    bits3 = []
+    if c.infrastructure:
+        bits3.append(f"In terms of infrastructure, the community has {c.infrastructure.rstrip('.').lower()}.")
+    if c.farmers_cooperative:
+        bits3.append(f"Cooperative structure: {c.farmers_cooperative.rstrip('.').lower()}.")
+    para3 = " ".join(bits3)
+
+    return "\n\n".join(p for p in (para1, para2, para3) if p)
+
+
+def demographic_narrative(data: PUEReportData) -> str:
+    iv = data.interviews
+    f = data.farmers
+    commodities = data.community.key_agro_commodities
+    crops = _join([cr.crop for cr in f.crops[:6]])
+    sme_types = _join([t.business_type for t in data.sme.types[:5]])
+
+    s = []
+    s.append(
+        f"A total of {iv.total:,} respondents were interviewed across the "
+        f"community, comprising {iv.farmers:,} farmers, {iv.agroprocessors:,} "
+        f"agro-processors, {iv.sme:,} SME operators and {iv.mobility:,} "
+        f"mobility operators.")
+    if f.male or f.female:
+        s.append(f"Among the farmers interviewed, {f.male:,} were male and "
+                 f"{f.female:,} female.")
+    if commodities:
+        s.append(f"The community's key agro-commodities are {commodities.rstrip('.')}.")
+    elif crops:
+        s.append(f"The most commonly cultivated crops include {crops}.")
+    if data.mobility.total:
+        s.append(f"Mobility activity is dominated by {data.mobility.okada:,} "
+                 f"okada and {data.mobility.tricycle:,} tricycle operators.")
+    if sme_types:
+        s.append(f"SME activity spans {sme_types}, among others.")
+    return " ".join(s)
+
+
+def processing_insights(data: PUEReportData) -> str:
+    p = data.processors
+    crops = _join([b.crop for b in p.business_models])
+    s = []
+    if p.male or p.female:
+        s.append(f"The community's agro-processing is carried out by "
+                 f"{p.male:,} male and {p.female:,} female processors.")
+    if crops:
+        s.append(f"Processing covers {crops}.")
+    # business model lean
+    cash = sum(b.cash_as_service for b in p.business_models)
+    goods = sum(b.goods_as_service for b in p.business_models)
+    if cash or goods:
+        lean = ("predominantly on a cash-for-service basis" if cash >= goods
+                else "predominantly on a goods-for-service basis")
+        s.append(f"Processors operate {lean}.")
+    if p.processing_quantities:
+        peak = sum(q.total_peak for q in p.processing_quantities)
+        scarce = sum(q.total_scarce for q in p.processing_quantities)
+        if peak and scarce:
+            s.append(f"Throughput is markedly seasonal: combined processing "
+                     f"falls from about {peak:,.0f} units in the peak season to "
+                     f"roughly {scarce:,.0f} in the scarce season, underlining "
+                     f"the case for reliable, lower-cost electric processing.")
+    return " ".join(s)
+
+
+def fill_missing(data: PUEReportData) -> PUEReportData:
+    """Populate any empty narrative slot with a deterministic fallback."""
+    if not data.narrative_overview.strip():
+        data.narrative_overview = community_overview(data)
+    if not data.narrative_demographic.strip():
+        data.narrative_demographic = demographic_narrative(data)
+    if not data.narrative_processing_insights.strip():
+        data.narrative_processing_insights = processing_insights(data)
+    return data

pue_report_agent/render.py

@@ -0,0 +1,911 @@
+"""
+render.py
+=========
+Deterministic .docx writer that reproduces the DREEF PUE report TEMPLATE's
+structure, tone, headings, captions, table of contents and list of tables for
+ANY community's data.
+
+What makes the output match the template:
+
+* **Title page** in the template's exact layout.
+* **Auto Table of Contents** — a real Word TOC field (\\o "1-3") that populates
+  and renumbers itself; set to update on open.
+* **Auto List of Tables** — a Word Table-of-Figures field keyed to the "Table"
+  caption sequence, so it always lists every table with the right page.
+* **SEQ-field caption numbering** — every caption is "Table " + a `SEQ Table`
+  field (or "Figure " + `SEQ Figure`). Word computes the numbers, so they are
+  always sequential and correct no matter how many tables a community needs.
+  Nothing is hard-numbered.
+* **Recomputed calculations** — totals come from calc.recompute(), never from a
+  possibly-wrong sheet total.
+* **Verbatim boilerplate** — pulled from templates.py so tone/wording match.
+
+The LLM's prose (narrative_* fields) drops into the three narrative slots; every
+number and table is deterministic.
+"""
+
+from __future__ import annotations
+
+from docx import Document
+from docx.enum.text import WD_ALIGN_PARAGRAPH
+from docx.enum.table import WD_TABLE_ALIGNMENT, WD_CELL_VERTICAL_ALIGNMENT
+from docx.oxml import OxmlElement
+from docx.oxml.ns import qn
+from docx.shared import Pt, RGBColor, Inches
+
+from .schema import PUEReportData
+from . import templates as T
+
+
+# --------------------------------------------------------------------------- #
+# Word field / caption helpers
+# --------------------------------------------------------------------------- #
+def _field(paragraph, instr: str, placeholder: str = "", size=None) -> None:
+    """Append a complex Word field (begin / instrText / separate / end)."""
+    run = paragraph.add_run()
+    if size is not None:
+        run.font.size = size
+    b = OxmlElement("w:fldChar"); b.set(qn("w:fldCharType"), "begin")
+    it = OxmlElement("w:instrText"); it.set(qn("xml:space"), "preserve")
+    it.text = instr
+    sep = OxmlElement("w:fldChar"); sep.set(qn("w:fldCharType"), "separate")
+    txt = OxmlElement("w:t"); txt.text = placeholder
+    end = OxmlElement("w:fldChar"); end.set(qn("w:fldCharType"), "end")
+    r = run._r
+    for el in (b, it, sep, txt, end):
+        r.append(el)
+
+
+def _toc(doc) -> None:
+    p = doc.add_paragraph()
+    _field(p, 'TOC \\o "1-3" \\h \\z \\u', "Right-click and Update Field to "
+           "build the Table of Contents.")
+
+
+def _list_of_tables(doc) -> None:
+    p = doc.add_paragraph()
+    # Table-of-Figures collecting the "Table" caption sequence.
+    _field(p, 'TOC \\h \\z \\c "Table"', "Right-click and Update Field to build "
+           "the List of Tables.")
+
+
+_ACRONYMS = {
+    "SME", "SMEs", "CO2", "CO\u2082", "GPS", "PUE", "IOT", "IoT", "BOQ", "SDG",
+    "SDGs", "SPV", "KPI", "MER", "LGA", "DREEF", "AI", "ESG", "PV", "NEW",
+    "kW", "kWh", "kWp", "MW", "MWh", "MWp", "hp", "II", "III", "IV",
+}
+_MINOR_WORDS = {"a", "an", "and", "as", "at", "but", "by", "for", "from", "in",
+                "of", "on", "or", "per", "the", "to", "vs", "with", "&"}
+
+
+def _title_case(text: str) -> str:
+    """Title-case a caption, preserving known acronyms/units and keeping minor
+    words lowercase (except the first word)."""
+    words = text.split(" ")
+    out = []
+    for i, w in enumerate(words):
+        if not w:
+            out.append(w)
+            continue
+        # Preserve tokens that are exactly a known acronym/unit.
+        if w in _ACRONYMS or w.upper() in {a.upper() for a in _ACRONYMS}:
+            match = next((a for a in _ACRONYMS if a.upper() == w.upper()), w)
+            out.append(match)
+            continue
+        # Keep tokens that contain digits as-is (e.g. "1ton/hr", "250l").
+        if any(ch.isdigit() for ch in w):
+            out.append(w)
+            continue
+        low = w.lower()
+        if i != 0 and low in _MINOR_WORDS:
+            out.append(low)
+        else:
+            out.append(w[0].upper() + w[1:])
+    return " ".join(out)
+
+
+def _caption(doc, text: str, seq: str = "Table") -> None:
+    """Auto-numbered caption: '<seq> N: text'.
+
+    Uses a real SEQ field (so Word's List of Tables can collect it AND it
+    renumbers if tables move), but caches the CORRECT current number as the
+    field's displayed value — so it reads 'Table 1', 'Table 2', ... immediately
+    on open, never the placeholder 'Table 0'."""
+    counters = getattr(doc, "_seq_counters", None)
+    if counters is None:
+        counters = {}
+        doc._seq_counters = counters
+    counters[seq] = counters.get(seq, 0) + 1
+    current = str(counters[seq])
+
+    style = "Caption" if "Caption" in [s.name for s in doc.styles] else None
+    p = doc.add_paragraph(style=style)
+    r1 = p.add_run(f"{seq} ")
+    r1.font.size = Pt(9); r1.font.bold = False; r1.font.italic = True
+    _field(p, f"SEQ {seq} \\* ARABIC", current, size=Pt(9))
+    r2 = p.add_run(f": {_title_case(text)}")
+    r2.font.size = Pt(9); r2.font.bold = False; r2.font.italic = True
+
+
+def _set_update_fields_on_open(doc) -> None:
+    """Make Word refresh TOC / List of Tables / SEQ numbers when first opened.
+
+    `w:updateFields` must appear in its schema-mandated position in
+    CT_Settings (before w:compat / w:rsids / w:mathPr / etc.), so we insert it
+    ahead of the first such trailing element rather than appending.
+    """
+    settings = doc.settings.element
+
+    # python-docx's default <w:zoom/> lacks the required percent attribute.
+    zoom = settings.find(qn("w:zoom"))
+    if zoom is not None and zoom.get(qn("w:percent")) is None:
+        zoom.set(qn("w:percent"), "100")
+
+    if settings.find(qn("w:updateFields")) is not None:
+        return
+    uf = OxmlElement("w:updateFields"); uf.set(qn("w:val"), "true")
+    # Elements that, per the schema, must come AFTER updateFields.
+    trailing = [qn(f"w:{t}") for t in (
+        "footnotePr", "endnotePr", "compat", "rsids", "mathPr",
+        "themeFontLang", "clrSchemeMapping", "shapeDefaults",
+        "decimalSymbol", "listSeparator")]
+    anchor = None
+    for child in settings:
+        if child.tag in trailing:
+            anchor = child
+            break
+    if anchor is not None:
+        anchor.addprevious(uf)
+    else:
+        settings.append(uf)
+
+
+# --------------------------------------------------------------------------- #
+# Table builder
+# --------------------------------------------------------------------------- #
+_HEADER_FILL = "1F4E79"
+_HEADER_TEXT = RGBColor(0xFF, 0xFF, 0xFF)
+
+
+def _shade(cell, fill: str) -> None:
+    tcPr = cell._tc.get_or_add_tcPr()
+    sh = OxmlElement("w:shd")
+    sh.set(qn("w:val"), "clear"); sh.set(qn("w:color"), "auto")
+    sh.set(qn("w:fill"), fill)
+    tcPr.append(sh)
+
+
+def _table(doc, headers, rows, widths=None, header_fill=_HEADER_FILL):
+    cols = len(headers)
+    tbl = doc.add_table(rows=1, cols=cols)
+    tbl.style = "Table Grid"
+    tbl.alignment = WD_TABLE_ALIGNMENT.CENTER
+    hdr = tbl.rows[0].cells
+    for i, h in enumerate(headers):
+        hdr[i].text = ""
+        run = hdr[i].paragraphs[0].add_run(str(h))
+        run.bold = True
+        run.font.color.rgb = _HEADER_TEXT
+        run.font.size = Pt(11)
+        _shade(hdr[i], header_fill)
+    for row in rows:
+        cells = tbl.add_row().cells
+        first = str(row[0]).strip().upper() if row and row[0] is not None else ""
+        is_total = first.startswith("TOTAL") or first in (
+            "GRAND TOTAL", "TOTAL COST", "TOTAL CExpense")
+        for i in range(cols):
+            val = row[i] if i < len(row) else ""
+            cells[i].text = ""
+            run = cells[i].paragraphs[0].add_run("" if val is None else str(val))
+            run.font.size = Pt(11)
+            if is_total:
+                run.bold = True
+    if widths:
+        for row in tbl.rows:
+            for i, w in enumerate(widths):
+                if i < len(row.cells):
+                    row.cells[i].width = w
+    return tbl
+
+
+def _machinery_table(doc, group: str, rows):
+    """Crop-group machinery table where the first column is a single cell
+    (the crop name, e.g. 'maize') vertically merged across every row and
+    centred, alongside a Machine | Specification / Power | Qty mini-table.
+    Works for any crop group (rice, sawmill, cassava, oil palm, ...)."""
+    n = 1 + len(rows)                       # header row + one per machine
+    tbl = doc.add_table(rows=n, cols=4)
+    tbl.style = "Table Grid"
+    tbl.alignment = WD_TABLE_ALIGNMENT.CENTER
+
+    def _put(cell, text, *, bold=False, white=False, size=11, center=False):
+        cell.text = ""
+        p = cell.paragraphs[0]
+        if center:
+            p.alignment = WD_ALIGN_PARAGRAPH.CENTER
+        run = p.add_run("" if text is None else str(text))
+        run.bold = bold
+        run.font.size = Pt(size)
+        if white:
+            run.font.color.rgb = _HEADER_TEXT
+
+    # Column-header row for the three right-hand columns.
+    for ci, htext in enumerate(("Machine", "Specification / Power", "Qty"), start=1):
+        _put(tbl.cell(0, ci), htext, bold=True, white=True)
+        _shade(tbl.cell(0, ci), _HEADER_FILL)
+    # Machine rows.
+    for ri, m in enumerate(rows, start=1):
+        _put(tbl.cell(ri, 1), m.machine)
+        _put(tbl.cell(ri, 2), m.specification)
+        _put(tbl.cell(ri, 3), m.count)
+
+    # Merge the entire first column into one centred crop-name cell.
+    merged = tbl.cell(0, 0).merge(tbl.cell(n - 1, 0))
+    merged.vertical_alignment = WD_CELL_VERTICAL_ALIGNMENT.CENTER
+    _put(merged, group, bold=True, white=True, center=True)
+    _shade(merged, _HEADER_FILL)
+    return tbl
+
+
+def _money(v) -> str:
+    return "" if v in (None, "") else f"{float(v):,.0f}"
+
+
+# Section headings the reference renders in full caps (matches item 9).
+_CAPS_HEADINGS = {
+    "introduction", "about the contractor", "project site and location",
+    "methodology used", "key findings",
+}
+
+
+def _heading(doc, text, level):
+    if text.strip().lower() in _CAPS_HEADINGS:
+        text = text.upper()
+    return doc.add_heading(text, level=level)
+
+
+# --------------------------------------------------------------------------- #
+# Main entry
+# --------------------------------------------------------------------------- #
+def render(data: PUEReportData, out_path: str,
+           developer: str = "the mini-grid developer",
+           report_date: str = "") -> str:
+    doc = Document()
+    doc._seq_counters = {}
+    _base_styles(doc)
+    from .fallback_narrative import fill_missing
+    fill_missing(data)
+    c = data.community
+
+    # ---- Title page -------------------------------------------------------
+    for _ in range(6):                       # push the title toward mid-page
+        doc.add_paragraph()
+    tp = doc.add_paragraph()
+    tp.alignment = WD_ALIGN_PARAGRAPH.CENTER
+    r = tp.add_run(T.TITLE_BLOCK["title"].format(community_upper=c.name.upper()))
+    r.bold = True; r.font.size = Pt(28)
+    doc.add_paragraph()
+    for i, line in enumerate(T.TITLE_BLOCK["subtitle_lines"]):
+        p = doc.add_paragraph(); p.alignment = WD_ALIGN_PARAGRAPH.CENTER
+        rr = p.add_run(line)
+        rr.font.size = Pt(14)
+        rr.bold = (i == len(T.TITLE_BLOCK["subtitle_lines"]) - 1)  # bold DREEF
+    if report_date:
+        for _ in range(4):
+            doc.add_paragraph()
+        p = doc.add_paragraph(); p.alignment = WD_ALIGN_PARAGRAPH.CENTER
+        rr = p.add_run(report_date); rr.font.size = Pt(13); rr.bold = True
+    doc.add_page_break()
+
+    # ---- Table of Contents -----------------------------------------------
+    _heading(doc, "Table of Contents", 1)
+    _toc(doc)
+    doc.add_page_break()
+
+    # ---- List of Tables ---------------------------------------------------
+    _heading(doc, "List of Tables", 1)
+    _list_of_tables(doc)
+    doc.add_page_break()
+
+    _introduction(doc, c, developer)
+    _project_site(doc, data, developer)
+    _methodology(doc)
+    _key_findings(doc, data)
+    _proposed_equipment(doc, data)
+    _infrastructure(doc, data)
+    _boq_budget(doc, data)
+    _financial_model(doc, data)
+    _revenue_per_user(doc, data)
+    _implementation_plan(doc, c)
+    _conditions_for_scaleup(doc)
+    _mer(doc, c)
+    _risks(doc, c)
+    _impact(doc, data)
+    _sdgs(doc)
+    _challenges(doc)
+    _ai_disclosure(doc)
+
+    _set_update_fields_on_open(doc)
+    doc.save(out_path)
+    return out_path
+
+
+# --------------------------------------------------------------------------- #
+# Section renderers (template order)
+# --------------------------------------------------------------------------- #
+def _base_styles(doc) -> None:
+    normal = doc.styles["Normal"]
+    normal.font.name = "Aptos"
+    normal.font.size = Pt(11)
+    # Apply Aptos to the other built-in styles we use (Word's defaults would
+    # otherwise keep Calibri Light on headings / Calibri on captions).
+    for sname in ("Title", "Heading 1", "Heading 2", "Heading 3",
+                  "Heading 4", "Caption"):
+        if sname in [s.name for s in doc.styles]:
+            doc.styles[sname].font.name = "Aptos"
+    if "Caption" in [s.name for s in doc.styles]:
+        cap = doc.styles["Caption"]
+        cap.font.size = Pt(9)
+        cap.font.bold = False
+        cap.font.italic = True
+
+
+def _add_hyperlink(paragraph, url, text, size=Pt(11)):
+    """Append a real external hyperlink run (blue, underlined) to a paragraph."""
+    part = paragraph.part
+    r_id = part.relate_to(
+        url, "http://schemas.openxmlformats.org/officeDocument/2006/"
+        "relationships/hyperlink", is_external=True)
+    link = OxmlElement("w:hyperlink")
+    link.set(qn("r:id"), r_id)
+    run = OxmlElement("w:r")
+    rPr = OxmlElement("w:rPr")
+    color = OxmlElement("w:color"); color.set(qn("w:val"), "0563C1")
+    u = OxmlElement("w:u"); u.set(qn("w:val"), "single")
+    rPr.append(color); rPr.append(u)
+    if size is not None:
+        sz = OxmlElement("w:sz"); sz.set(qn("w:val"), str(int(size.pt * 2)))
+        rPr.append(sz)
+    run.append(rPr)
+    t = OxmlElement("w:t"); t.set(qn("xml:space"), "preserve"); t.text = text
+    run.append(t)
+    link.append(run)
+    paragraph._p.append(link)
+    return link
+
+
+def _introduction(doc, c, developer):
+    _heading(doc, "Introduction", 1)
+    intro = T.INTRODUCTION
+    doc.add_paragraph(intro["lead"].format(community=c.name, developer=developer))
+    doc.add_paragraph(intro["objectives_lead"])
+    for obj in intro["objectives"]:
+        doc.add_paragraph(obj, style="List Bullet")
+    doc.add_paragraph(intro["closing"])
+
+    _heading(doc, "About the Contractor", 1)
+    ac = T.ABOUT_CONTRACTOR
+    doc.add_paragraph(ac["body"])
+    p = doc.add_paragraph()
+    r = p.add_run(ac["link_lead"]); r.font.size = Pt(11)
+    _add_hyperlink(p, ac["link_url"], ac["link_text"])
+    tail = p.add_run(ac["link_tail"]); tail.font.size = Pt(11)
+
+
+def _project_site(doc, data, developer):
+    c = data.community
+    _heading(doc, "Project Site and Location", 1)
+    _heading(doc, f"{c.name} Community Overview", 2)
+    for para in (data.narrative_overview or "").split("\n\n"):
+        if para.strip():
+            doc.add_paragraph(para.strip())
+
+    _heading(doc, "Geographic Profile", 2)
+    _table(doc, ["Community Name", "LGA", "Coordinates (Lat, Long)", "State"],
+           [[c.name, c.lga, f"{c.latitude}, {c.longitude}", c.state]])
+    _caption(doc, "GPS of community")
+
+    _heading(doc, "Demographic and Socio Economic Profile", 2)
+    for para in (data.narrative_demographic or "").split("\n\n"):
+        if para.strip():
+            doc.add_paragraph(para.strip())
+    _table(doc, ["Category", "Details"], [
+        ["Topography and Climate", c.topography_climate],
+        ["Land Use", c.land_use],
+        ["Population Estimates", c.population_estimate],
+        ["Number of Households", c.households],
+        ["Major Ethnic Groups", c.major_ethnic_groups],
+        ["Languages Spoken", c.languages_spoken],
+        ["Key Economic Activities", c.key_economic_activities],
+        ["Key Agro Commodities", c.key_agro_commodities],
+        ["Processing Methods", c.processing_methods],
+        ["Number of Agro-Processors", c.num_agro_processors],
+        ["Farmers' Cooperative", c.farmers_cooperative],
+        ["Infrastructure", c.infrastructure],
+        ["Security & Social Risks", c.security_social_risks],
+    ])
+    _caption(doc, "Demographic and Socio Economic Profile of community")
+
+    # Mini-grid + micro capacities (developer-supplied)
+    _heading(doc, "Mini-Grid Development Project", 2)
+    _capacity_block(doc, data.minigrid)
+    _heading(doc, "Micro Stand Alone Energy System Development Project", 2)
+    _capacity_block(doc, data.microgrid)
+
+    _heading(doc, "Energy Substitution for Different Activities", 2)
+    doc.add_paragraph("The mini grid will replace or supplement existing energy "
+                      "sources as outlined below:")
+    # Only crops with actual processing activity belong here — otherwise the
+    # list fills with template crop rows that have all-zero data (Abigi carries
+    # cocoa, sesame, kolanut, millet... at zero alongside cassava/oil palm).
+    def _bm_active(b):
+        return (b.male or b.female or b.cash_as_service or b.goods_as_service
+                or b.purchase_raw_materials)
+    crops = [b.crop for b in data.processors.business_models if _bm_active(b)] \
+        or [b.crop for b in data.processors.business_models] \
+        or [m.crop_group for m in data.processors.machinery]
+    seen, crop_list = set(), []
+    for cr in crops:
+        key = cr.strip().lower()
+        if key and key not in seen:
+            seen.add(key); crop_list.append(cr.strip())
+    proc_label = ("Processing (" + ", ".join(crop_list) + ")") if crop_list \
+        else "Agro-processing"
+    energy_sub = [
+        ("Household lighting", "Kerosene lamps, petrol generators",
+         "Solar electricity"),
+        (proc_label, "Diesel/petrol engines", "Electric PUE machines"),
+        ("SME", "Small petrol generators", "Reliable solar mini-grid power"),
+        ("Mobility", "Petrol powered two-wheelers",
+         "Electric powered two-wheelers"),
+    ]
+    _table(doc, ["Use Case", "Current Energy Source", "Replacement"],
+           [list(r) for r in energy_sub])
+    _caption(doc, "Energy Substitution for Different Activities")
+
+    _heading(doc, "Distance from Processing Sites to Proposed Minigrid", 2)
+    if data.processor_distances:
+        _table(doc, ["Name of Processor", "Site GPS", "Minigrid GPS",
+                     "Distance (km)"],
+               [[d.name, f"{d.site_lat}, {d.site_long}" if d.site_lat else "",
+                 d.minigrid_gps, d.distance_km]
+                for d in data.processor_distances])
+    else:
+        _table(doc, ["Name of Processor", "Site GPS", "Minigrid GPS",
+                     "Distance (km)"], [["", "", "", ""]])
+    _caption(doc, "Distance from Processing Sites to Proposed Minigrid")
+
+
+def _capacity_block(doc, spec):
+    _heading(doc, "Proposed Capacity", 3)
+    doc.add_paragraph(f"Solar PV: {spec.solar_pv or '[to be supplied]'}",
+                      style="List Bullet")
+    if spec.inverter:
+        doc.add_paragraph(f"PV Inverter: {spec.inverter}", style="List Bullet")
+    doc.add_paragraph(f"Battery Storage: {spec.battery_storage or '[to be supplied]'}",
+                      style="List Bullet")
+    doc.add_paragraph(f"Annual Consumption: {spec.annual_consumption or '[to be supplied]'}",
+                      style="List Bullet")
+    _heading(doc, "Distribution Metrics", 3)
+    if spec.distribution_metrics:
+        for d in spec.distribution_metrics:
+            doc.add_paragraph(f"{d.end_user} ({d.percentage}): {d.description}",
+                              style="List Bullet")
+    else:
+        doc.add_paragraph("[Distribution metrics to be supplied by the "
+                          "mini-grid developer.]", style="List Bullet")
+
+
+def _methodology(doc):
+    _heading(doc, "Methodology Used", 1)
+    _heading(doc, T.METHODOLOGY_HEADING, 2)
+    doc.add_paragraph(T.METHODOLOGY)
+
+
+def _key_findings(doc, data):
+    c = data.community
+    _heading(doc, "Key Findings", 1)
+    _heading(doc, f"Income Generating Activities of {c.name}", 2)
+    iv = data.interviews
+    _table(doc, ["People interviewed", str(iv.total)],
+           [["Farmer", iv.farmers], ["Agroprocessors", iv.agroprocessors],
+            ["SME", iv.sme], ["Mobility", iv.mobility]])
+    _caption(doc, "Income generating activities")
+
+    # Farmers
+    _heading(doc, "Farmers", 2)
+    _table(doc, ["Gender", "Number of Farmers"],
+           [["Male", data.farmers.male], ["Female", data.farmers.female]])
+    _caption(doc, "Gender of interviewed Farmers")
+    if data.farmers.crops:
+        _crops = [cr for cr in data.farmers.crops
+                  if cr.farming_households or cr.annual_production_interviewed
+                  or cr.estimated_annual_production_community]
+        if _crops:
+            _table(doc, ["Crop", "Farming household", "Percentage",
+                     "Annual Production Interviewed",
+                     "Estimated Annual Production (100kg bag) Community",
+                     "Total Area Planted (m²)"],
+               [[cr.crop, cr.farming_households, f"{cr.percentage:.1f}",
+                 f"{cr.annual_production_interviewed:,.0f}",
+                 f"{cr.estimated_annual_production_community:,.2f}",
+                 f"{cr.total_area_planted_hectares:,.0f}"]
+                for cr in _crops])
+            _caption(doc, "Total Annual Quantity Harvested")
+
+    # Agro-processing
+    _heading(doc, "Agro Processing", 2)
+    if (data.narrative_processing_insights or "").strip():
+        doc.add_paragraph(data.narrative_processing_insights.strip())
+    _table(doc, ["Gender", "Number of Agroprocessors"],
+           [["Male", data.processors.male], ["Female", data.processors.female]])
+    _caption(doc, "Processing distribution according to Gender")
+    if data.processors.business_models:
+        _bms = [b for b in data.processors.business_models
+                if (b.male or b.female or b.cash_as_service
+                    or b.goods_as_service or b.purchase_raw_materials)]
+        if _bms:
+            _table(doc, ["Crops Processed", "Male", "Female", "cash as a service",
+                     "goods as a service", "purchase raw materials"],
+               [[b.crop, b.male, b.female, b.cash_as_service,
+                 b.goods_as_service, b.purchase_raw_materials]
+                for b in _bms])
+            _caption(doc, "Processing distribution according to business model")
+
+    # One machinery table per crop group (adapts to any community). When the
+    # rows carry the richer columns (power source / rated power / capacity),
+    # render those; otherwise keep the compact Machine | Specification | Qty
+    # layout (Jaji's reference style).
+    groups = []
+    for m in data.processors.machinery:
+        if m.crop_group not in groups:
+            groups.append(m.crop_group)
+    for g in groups:
+        rows = [m for m in data.processors.machinery if m.crop_group == g]
+        # The flat extractor tags rows "processing equipment" — those are the
+        # communities (e.g. Abigi) that supply Power Source / Rated Power /
+        # Capacity. Jaji-style crop-grouped rows keep the compact layout so
+        # their tables stay faithful to that reference.
+        rich = (g == "processing equipment")
+        has_cap = any(m.capacity for m in rows)
+        if rich:
+            headers = [g, "Power Source", "Rated Power"]
+            if has_cap:
+                headers.append("Capacity")
+            headers.append("Qty")
+            body = []
+            for m in rows:
+                row = [m.machine, m.power_source, m.rated_power]
+                if has_cap:
+                    row.append(m.capacity)
+                row.append(m.count)
+                body.append(row)
+            _table(doc, headers, body)
+        else:
+            _machinery_table(doc, g, rows)
+        _caption(doc, f"Machinery Profile of {g}")
+
+    if data.processors.processing_quantities:
+        _table(doc, ["Crops Processed", "Total Quantity Processed (Peak)",
+                     "Total Quantity Processed (Scarce)", "Average Quantity (Peak)",
+                     "Average Quantity Processed (Scarce)"],
+               [[q.crop, f"{q.total_peak:,.0f}", f"{q.total_scarce:,.0f}",
+                 f"{q.avg_peak:,.0f}", f"{q.avg_scarce:,.1f}"]
+                for q in data.processors.processing_quantities])
+        _caption(doc, "Processing insight")
+
+    # CO2 emission assessment for the fuel-powered processing machines.
+    co2 = data.processors.co2_assessment
+    if co2:
+        _heading(doc, "CO\u2082 Emission Assessment", 3)
+        body = []
+        tot_n = tot_l = tot_c = 0.0
+        any_l = any_c = False
+        for r in co2:
+            litres = "" if r.annual_fuel_litres is None else f"{r.annual_fuel_litres:,.0f}"
+            kg = "" if r.co2_kg is None else f"{r.co2_kg:,.2f}"
+            body.append([r.machine, r.specification, r.fuel_type,
+                         r.num_machines, litres, kg])
+            tot_n += r.num_machines
+            if r.annual_fuel_litres is not None:
+                tot_l += r.annual_fuel_litres; any_l = True
+            if r.co2_kg is not None:
+                tot_c += r.co2_kg; any_c = True
+        body.append(["Total", "", "", f"{tot_n:g}",
+                     f"{tot_l:,.0f}" if any_l else "",
+                     f"{tot_c:,.2f}" if any_c else ""])
+        _table(doc, ["Machine", "Specification", "Fuel Type", "No. of Machines",
+                     "Annual Fuel Consumption (L)", "CO\u2082 Emissions (kg CO\u2082/year)"],
+               body)
+        _caption(doc, "Annual CO\u2082 Emissions from Fuel-Powered Engines")
+        doc.add_paragraph(
+            "Note: IPCC emission factors are 2.31 kg CO\u2082 per litre of petrol "
+            "and 2.86 kg CO\u2082 per litre of diesel. Where annual fuel "
+            "consumption is not yet available, emissions are pending that input.")
+
+
+    # Mobility
+    _heading(doc, "Mobility", 2)
+    mob = data.mobility
+    _table(doc, ["E-Mobility", str(mob.total)],
+           [["Okada", mob.okada], ["Tricycle", mob.tricycle],
+            ["Boat", mob.boat]])
+    _caption(doc, "Mobility interviewed")
+
+    def _money_block(label, total, avg, caption):
+        if total is None and avg is None:
+            return
+        _table(doc, [label, "Value (\u20a6)"],
+               [["Total", "" if total is None else f"{total:,.2f}"],
+                ["Average", "" if avg is None else f"{avg:,.2f}"]])
+        _caption(doc, caption)
+
+    _money_block("Daily Revenue", mob.daily_revenue_total,
+                 mob.daily_revenue_avg, "Daily Revenue")
+    _money_block("Daily Expenses (Fuel)", mob.daily_fuel_expense_total,
+                 mob.daily_fuel_expense_avg, "Daily Expenses (Fuel)")
+    _money_block("Daily Profit", mob.daily_profit_total,
+                 mob.daily_profit_avg, "Daily Profit")
+
+    # SME
+    _heading(doc, "SME", 2)
+    _table(doc, ["SME", str(data.sme.total)],
+           [[t.business_type, t.count] for t in data.sme.types])
+    _caption(doc, "SME interviewed")
+
+
+def _fmt_cell(v):
+    if v is None:
+        return ""
+    if isinstance(v, float):
+        return f"{v:,.2f}".rstrip("0").rstrip(".") if v % 1 else f"{int(v):,}"
+    if isinstance(v, int):
+        return f"{v:,}"
+    return str(v)
+
+
+def _equipment_tables(doc, plan, phase_label):
+    """Render one table per equipment section, using that section's OWN
+    columns (agro-processing and the Swap Station have different headers)."""
+    for sec in plan.sections:
+        headers = sec.headers or ["Item"]
+        body = [[_fmt_cell(v) for v in row] for row in sec.rows]
+        if sec.total_row:
+            body.append([_fmt_cell(v) for v in sec.total_row])
+        _table(doc, headers, body)
+        _caption(doc, f"{sec.name} ({phase_label})")
+
+
+def _proposed_equipment(doc, data):
+    _heading(doc, "Proposed PUE Equipment", 1)
+    _heading(doc, "ScaleUp Phase", 2)
+    _equipment_tables(doc, data.equipment_scaleup, "Scaleup")
+    _scaleup = data.equipment_scaleup
+    if _scaleup.projection:
+        _heading(doc, "Total Energy Projection for Micro Stand Alone System", 3)
+        rows = [[p.item, f"{p.kwh:,.2f}", f"{p.six_hour_day:,.2f}"]
+                for p in _scaleup.projection]
+        rows.append(["TOTAL", f"{(_scaleup.projection_total_kwh or 0):,.2f}",
+                     f"{(_scaleup.projection_total_six_hour or 0):,.2f}"])
+        _table(doc, ["ITEM", "Power Consumption (kWh)", "6-Hour Day Work (kWh)"],
+               rows)
+        _caption(doc, "Total Energy Projection (Scale-Up Phase)")
+    _heading(doc, "Pilot Phase", 2)
+    _equipment_tables(doc, data.equipment_pilot, "Pilot")
+
+    _heading(doc, "Total Energy Projection for PUE Pilot Micro Stand Alone System", 2)
+    plan = data.equipment_pilot
+    rows = [[p.item, f"{p.kwh:,.2f}", f"{p.six_hour_day:,.2f}"]
+            for p in plan.projection]
+    rows.append(["TOTAL", f"{(plan.projection_total_kwh or 0):,.2f}",
+                 f"{(plan.projection_total_six_hour or 0):,.2f}"])
+    _table(doc, ["ITEM", "kW/hr", "6 hour day work"], rows)
+    _caption(doc, "Total Energy Projection \u2013 Pilot")
+
+
+def _infrastructure(doc, data):
+    _heading(doc, "Detailed Pilot Infrastructure Specifications", 1)
+    _heading(doc, "AgroHub Pilot Infrastructure Specifications", 2)
+    doc.add_paragraph(T.AGROHUB_SPEC_INTRO)
+    for b in T.AGROHUB_SPEC_BULLETS:
+        doc.add_paragraph(b, style="List Bullet")
+    _heading(doc, "Land & Building Layout", 2)
+    for b in T.LAND_BUILDING_LAYOUT:
+        doc.add_paragraph(b, style="List Bullet")
+    _table(doc, ["Room / Area", "Dimension (m)", "Area (m²)",
+                 "Notes / IoT Deployment"],
+           [list(r) for r in T.INFRA_LAYOUT_TABLE])
+    _caption(doc, "Pilot Phase Layout \u2013 IoT Enabled")
+    for s in T.STRUCTURAL_FEATURES:
+        doc.add_paragraph(s, style="List Bullet")
+    _heading(doc, "Cooperative Governance & Operational Arrangement", 2)
+    _table(doc, ["Structure", "Description"],
+           [list(r) for r in T.COOP_GOVERNANCE])
+    _caption(doc, "Cooperative Governance & Operational Arrangement")
+    _heading(doc, "Safety and Compliance", 2)
+    _table(doc, ["Aspect", "Implementation"],
+           [list(r) for r in T.SAFETY_COMPLIANCE])
+    _caption(doc, "Safety and Compliance")
+    _heading(doc, "Security Features", 2)
+    for s in T.SECURITY_FEATURES:
+        doc.add_paragraph(s, style="List Bullet")
+    # Figure (placeholder box with a correctly-numbered caption)
+    p = doc.add_paragraph(); p.alignment = WD_ALIGN_PARAGRAPH.CENTER
+    p.add_run("[ " + T.FIGURE_AGROHUB + " image ]").italic = True
+    counters = doc._seq_counters
+    counters["Figure"] = counters.get("Figure", 0) + 1
+    fp = doc.add_paragraph(); fp.alignment = WD_ALIGN_PARAGRAPH.CENTER
+    style = "Caption" if "Caption" in [s.name for s in doc.styles] else None
+    if style:
+        fp.style = style
+    fp.add_run("Figure ")
+    _field(fp, "SEQ Figure \\* ARABIC", str(counters["Figure"]))
+    fp.add_run(f": {T.FIGURE_AGROHUB}")
+
+
+def _boq_budget(doc, data):
+    _heading(doc, "BOQ & Budget", 1)
+    doc.add_paragraph("The Bill of Quantity is for the Agrohub model; budgets "
+                      "for other models are available in the financial model "
+                      "worksheet. The breakdown of the budget is listed below.")
+    for s in data.budget.sections:
+        _heading(doc, s.name, 2)
+        body = [[i.item, i.details, i.quantity, _money(i.unit_price),
+                 _money(i.total_price)] for i in s.items]
+        body.append(["TOTAL", "", "", "", _money(s.total)])
+        _table(doc, ["Item", "Details", "Quantity", "Unit Price",
+                     "Total Price"], body)
+        _caption(doc, f"{s.name} budget")
+    _heading(doc, "Grand Total", 2)
+    rows = [[i + 1, s.name, _money(s.total)]
+            for i, s in enumerate(data.budget.sections)]
+    rows.append(["", "TOTAL", _money(data.budget.grand_total)])
+    _table(doc, ["S/N", "ITEM", "PRICE (₦)"], rows)
+    _caption(doc, "Total PUE Pilot budget")
+
+
+def _financial_model(doc, data):
+    _heading(doc, "Financial Model", 1)
+    c = data.community
+    doc.add_paragraph(f"For the financial model for the deployment of PUE in "
+                      f"{c.name} community, several models were tested to find "
+                      f"the best fit which ensures affordability while providing "
+                      f"the appropriate productive-use technology for this pilot "
+                      f"phase. The models are stated below.")
+    _table(doc, ["Business Model", "Explanation"],
+           [list(r) for r in T.IMPLEMENTATION_MODELS_FULL])
+    _caption(doc, "Various Implementation models")
+
+    _heading(doc, "Monthly Revenue", 2)
+    for m in data.financial_models:
+        body = [[m.model_name if i == 0 else "", r.beneficiary, r.quantity,
+                 f"{r.timeframe_months:.0f}", f"{r.amount_monthly:,.0f}"]
+                for i, r in enumerate(m.rows)]
+        _table(doc, ["Business Model", "Beneficiaries", "Quantity",
+                     "Timeframe (months)", "Amount (monthly)"], body)
+        _caption(doc, m.model_name)
+
+
+def _revenue_per_user(doc, data):
+    _heading(doc, "Revenue Per User", 1)
+    doc.add_paragraph("Projected revenue per user for the mini-grid and the "
+                      "contribution of each category is shown below.")
+    if data.revenue_per_user:
+        _table(doc, ["Category", "Effective Daily Demand (kWh)",
+                     "Effective Annual Demand (kWh)", "No of Beneficiaries",
+                     "Average kWh Tariff", "Daily Revenue per Category (#/kWh)",
+                     "Daily Average Revenue (#/kWh)"],
+               [[r.category, f"{r.effective_daily_demand_kwh:,.2f}",
+                 f"{r.effective_annual_demand_kwh:,.2f}", r.beneficiaries,
+                 f"{r.avg_tariff:,.3f}", f"{r.daily_revenue_category:,.2f}",
+                 f"{r.daily_avg_revenue:,.2f}"] for r in data.revenue_per_user])
+    else:
+        _table(doc, ["Category", "Effective Daily Demand (kWh)",
+                     "Effective Annual Demand (kWh)", "No of Beneficiaries",
+                     "Average kWh Tariff", "Daily Revenue per Category (#/kWh)",
+                     "Daily Average Revenue (#/kWh)"], [["", "", "", "", "", "", ""]])
+    _caption(doc, "Average revenue per user")
+
+
+def _implementation_plan(doc, c):
+    _heading(doc, "Implementation Plan", 1)
+    doc.add_paragraph(T.IMPLEMENTATION_PLAN_INTRO.format(community=c.name))
+    _table(doc, ["S/N", "Title", "Responsibility", "Duration", "Timeline"],
+           [list(r) for r in T.IMPLEMENTATION_PLAN])
+    _caption(doc, "Implementation plan")
+
+
+def _conditions_for_scaleup(doc):
+    _heading(doc, "Conditions for Scaleup", 1)
+    doc.add_paragraph(T.SCALEUP_INTRO)
+    for section_title, items in T.SCALEUP_SECTIONS:
+        _heading(doc, section_title, 2)
+        for sub_title, bullets in items:
+            _heading(doc, sub_title, 3)
+            for b in bullets:
+                doc.add_paragraph(b, style="List Bullet")
+    _heading(doc, "Practical \u201cGo/No-Go\u201d Scale-Up Gate", 2)
+    doc.add_paragraph("Scale-up is activated when ALL conditions below are met:")
+    for g in T.SCALEUP_GATE:
+        doc.add_paragraph(g, style="List Bullet")
+
+
+def _mer(doc, c):
+    _heading(doc, "Monitoring, Evaluation & Reporting (MER)", 1)
+    doc.add_paragraph(T.MER_INTRO.format(community=c.name))
+    _heading(doc, "Key Performance Indicators (KPIs)", 2)
+    _table(doc, ["KPI Category", "Indicator", "Frequency"], T.KPIS)
+    _caption(doc, "KPI")
+    _heading(doc, "Data Collection and Reporting Tools", 2)
+    _table(doc, ["Tool / System", "Purpose", "Managed By"],
+           [list(r) for r in T.DATA_TOOLS])
+    _caption(doc, "Data Collection and Reporting Tools")
+    _heading(doc, "Feedback Loops", 2)
+    _table(doc, ["S/N", "Item", "Who", "Frequency", "Purpose"],
+           [list(r) for r in T.FEEDBACK_LOOPS])
+    _caption(doc, "Feedback Loops")
+
+
+def _risks(doc, c):
+    _heading(doc, "Risk Assessment and Mitigation", 1)
+    doc.add_paragraph(f"Deploying Productive Use of Energy (PUE) infrastructure "
+                      f"in {c.name} presents several operational, financial, "
+                      f"social, and institutional risks. This section outlines "
+                      f"the key risks anticipated and the strategic mitigation "
+                      f"measures integrated into the implementation design.")
+    _heading(doc, "Risks Identified", 2)
+    _table(doc, ["Risk Category", "Description"], T.RISKS_IDENTIFIED)
+    _caption(doc, "Risks Identified")
+    _heading(doc, "Mitigation Measures", 2)
+    _table(doc, ["Risk", "Mitigation Strategy"], T.MITIGATION_MEASURES)
+    _caption(doc, "Mitigation Measures")
+
+
+def _impact(doc, data):
+    _heading(doc, "Proposed Impact of the PUE on the Community", 1)
+    c = data.community
+    doc.add_paragraph(f"The implementation of Productive Use of Energy (PUE) "
+                      f"infrastructure and equipment in {c.name} is projected to "
+                      f"catalyze a range of socioeconomic, environmental, and "
+                      f"institutional benefits, addressing long-standing "
+                      f"challenges in agro-processing, transportation, energy "
+                      f"access, and rural livelihoods.")
+    rows = ([[r.impact_area, r.metric, r.projected_outcome]
+             for r in data.projected_impact]
+            or [list(r) for r in T.PROJECTED_IMPACT_DEFAULT])
+    _table(doc, ["Impact Area", "Metric", "Projected Outcome"], rows)
+    _caption(doc, "Summary of Projected Outcomes by Year 1")
+
+
+def _sdgs(doc):
+    _heading(doc, "Contribution to the Sustainable Development Goals (SDGs)", 1)
+    doc.add_paragraph("The project directly contributes to several SDGs by "
+                      "integrating clean energy into productive rural "
+                      "enterprises.")
+    _table(doc, ["SDG", "Goal Description", "Project Contribution"], T.SDGS)
+    _caption(doc, "Project Alignment with SDGs")
+
+
+def _challenges(doc):
+    _heading(doc, "Challenges And Recommendations", 1)
+    _heading(doc, "Key Challenges", 2)
+    _table(doc, ["Lesson Learned", "Recommended Best Practice"],
+           [list(r) for r in T.KEY_CHALLENGES])
+    _caption(doc, "Key Challenges and recommendations")
+    _heading(doc, "Forecasted Implementation Challenge", 2)
+    _table(doc, ["Lesson Learned", "Recommended Best Practice"],
+           [list(r) for r in T.FORECASTED_CHALLENGES])
+    _caption(doc, "Forecasted Implementation Challenge and recommendation")
+
+
+def _ai_disclosure(doc):
+    _heading(doc, "Use of Artificial Intelligence (AI) in Report Development", 1)
+    block = T.AI_DISCLOSURE
+    for para in block["intro"]:
+        doc.add_paragraph(para)
+    for label, text in block["sources"]:
+        p = doc.add_paragraph(style="List Bullet")
+        run = p.add_run(f"{label}: ")
+        run.bold = True
+        p.add_run(text)
+    doc.add_paragraph(block["closing"])

pue_report_agent/schema.py

@@ -0,0 +1,336 @@
+"""
+schema.py
+=========
+The canonical, validated representation of everything a PUE report needs.
+
+This is the contract between extraction (reading the master sheet) and
+generation (writing the report). The extractor's only job is to fill one of
+these objects; the generator's only job is to turn a filled one into a
+document. Nothing else in the system should read the raw spreadsheet.
+
+Design notes derived from reviewing the Jaji and Kwarua Tasha pairs:
+
+* `minigrid` / `microgrid` capacities do NOT come from the survey data. They
+  are supplied by the mini-grid developer and live in the Key Findings sheet
+  as hardcoded values (and are sometimes stale). They are modelled as optional
+  + overridable so the agent can flag/replace them.
+* Several report sections are pure boilerplate (risks, KPIs, scale-up gates,
+  SDGs, methodology). They are NOT in this schema at all — they live in
+  templates.py. Only community-specific, data-driven content is modelled here.
+* Every field that the report renders as a table is modelled as a list of rows
+  so the generator can emit it without re-deriving anything.
+"""
+
+from __future__ import annotations
+
+from typing import Optional
+from pydantic import BaseModel, Field
+
+
+# --------------------------------------------------------------------------- #
+# Community profile  (source: ESG sheet + Key Findings)
+# --------------------------------------------------------------------------- #
+class CommunityProfile(BaseModel):
+    name: str
+    lga: str
+    state: str
+    latitude: float
+    longitude: float
+
+    topography_climate: str = ""
+    land_use: str = ""
+    population_estimate: Optional[int] = None
+    households: Optional[int] = None
+    major_ethnic_groups: str = ""
+    languages_spoken: str = ""
+    key_economic_activities: str = ""
+    key_agro_commodities: str = ""
+    processing_methods: str = ""
+    num_agro_processors: Optional[int] = None
+    farmers_cooperative: str = ""
+    infrastructure: str = ""
+    security_social_risks: str = ""
+
+    # Free-text fields the ESG sheet supplies that feed the narrative overview
+    landmarks: str = ""
+    grid_status: str = ""
+    network_available: str = ""
+    water_sources: str = ""
+    community_sentiment: str = ""
+    land_ownership: str = ""
+    community_structures: str = ""
+
+
+# --------------------------------------------------------------------------- #
+# Energy system capacities  (source: Key Findings — developer-supplied)
+# --------------------------------------------------------------------------- #
+class EnergySystemSpec(BaseModel):
+    """Used for both the mini-grid and the micro stand-alone system."""
+    solar_pv: str = ""          # e.g. "6.45 MWp"
+    inverter: str = ""          # e.g. "6.93 MW" (PV Inverter)
+    battery_storage: str = ""   # e.g. "10 MWh"
+    annual_consumption: str = ""  # e.g. "5 MW" / "47,692.8 kWh"
+    distribution_metrics: list["DistributionLine"] = Field(default_factory=list)
+    developer_supplied: bool = True
+    needs_review: bool = False  # set True when value looks stale/templated
+
+
+class DistributionLine(BaseModel):
+    end_user: str       # "Residential", "Agricultural Processing", etc.
+    percentage: str     # "76%"
+    description: str = ""
+
+
+# --------------------------------------------------------------------------- #
+# Interview counts  (source: Key Findings "People interviewed")
+# --------------------------------------------------------------------------- #
+class InterviewCounts(BaseModel):
+    total: int
+    farmers: int
+    agroprocessors: int
+    sme: int
+    mobility: int
+
+
+# --------------------------------------------------------------------------- #
+# Farmers  (source: Farmers Analysis Sheet + Key Findings crop table)
+# --------------------------------------------------------------------------- #
+class CropRow(BaseModel):
+    crop: str
+    farming_households: int
+    percentage: float
+    annual_production_interviewed: float
+    estimated_annual_production_community: float
+    total_area_planted_hectares: float
+
+
+class FarmerAnalysis(BaseModel):
+    male: int
+    female: int
+    crops: list[CropRow] = Field(default_factory=list)
+
+
+# --------------------------------------------------------------------------- #
+# Processors  (source: Processors Analysis Sheet + Processors raw)
+# --------------------------------------------------------------------------- #
+class MachineRow(BaseModel):
+    crop_group: str        # "maize", "rice", "saw mill", "multiple grains"
+    machine: str
+    specification: str
+    count: int
+    # Richer columns some communities provide (e.g. Abigi). Parsed from the
+    # specification where possible; blank when the sheet doesn't supply them.
+    power_source: str = ""   # "Petrol", "Diesel", "Electric", "Manual"
+    rated_power: str = ""    # "13hp", "15 HP electric motor", ...
+    capacity: str = ""       # "20 bags", "348 Palm kernel bags", ...
+
+
+class ProcessingQtyRow(BaseModel):
+    crop: str
+    total_peak: float
+    total_scarce: float
+    avg_peak: float
+    avg_scarce: float
+
+
+# --------------------------------------------------------------------------- #
+# CO2 emission assessment  (fuel-powered processing machines)
+# --------------------------------------------------------------------------- #
+class CO2EmissionRow(BaseModel):
+    """One fuel-powered machine line in the CO2 assessment.
+
+    co2_kg is computed deterministically as annual_fuel_litres * the IPCC
+    emission factor for the fuel (2.31 kg CO2/L petrol, 2.86 kg CO2/L diesel).
+    annual_fuel_litres is left None when the sheet doesn't supply per-machine
+    fuel consumption (in which case co2_kg is also None and a warning is added).
+    """
+    machine: str
+    specification: str = ""
+    fuel_type: str = ""
+    num_machines: int = 0
+    annual_fuel_litres: Optional[float] = None
+    co2_kg: Optional[float] = None
+
+
+class BusinessModelRow(BaseModel):
+    crop: str
+    male: int
+    female: int
+    cash_as_service: int
+    goods_as_service: int
+    purchase_raw_materials: int
+
+
+class ProcessorAnalysis(BaseModel):
+    male: int
+    female: int
+    business_models: list[BusinessModelRow] = Field(default_factory=list)
+    machinery: list[MachineRow] = Field(default_factory=list)
+    processing_quantities: list[ProcessingQtyRow] = Field(default_factory=list)
+    co2_assessment: list[CO2EmissionRow] = Field(default_factory=list)
+
+
+# --------------------------------------------------------------------------- #
+# Mobility  (source: E-Mobility Analysis Sheet)
+# --------------------------------------------------------------------------- #
+class MobilityAnalysis(BaseModel):
+    total: int
+    okada: int
+    tricycle: int
+    boat: int
+    daily_revenue_total: Optional[float] = None
+    daily_revenue_avg: Optional[float] = None
+    daily_fuel_expense_total: Optional[float] = None
+    daily_fuel_expense_avg: Optional[float] = None
+    daily_profit_total: Optional[float] = None
+    daily_profit_avg: Optional[float] = None
+    daily_operation_hours: Optional[float] = None
+
+
+# --------------------------------------------------------------------------- #
+# SME  (source: SME Analysis Sheet)
+# --------------------------------------------------------------------------- #
+class SMETypeRow(BaseModel):
+    business_type: str
+    count: int
+
+
+class SMEAnalysis(BaseModel):
+    total: int
+    types: list[SMETypeRow] = Field(default_factory=list)
+
+
+# --------------------------------------------------------------------------- #
+# Proposed equipment  (source: Proposed Pilot / ScaleUp PUE Equipment)
+# --------------------------------------------------------------------------- #
+class EquipmentSection(BaseModel):
+    """One equipment block with its OWN native columns.
+
+    Equipment blocks differ by section: agro-processing uses
+    Machine|Capacity|Power rating|Quantity|Energy Source, while the Swap Station
+    uses E-Mobility Vehicles|Capacity|Quantity|Charging Rate|Charging Time. We
+    keep each block's real headers and rows so nothing is mis-mapped, and a
+    recomputed TOTAL row is added for the numeric columns."""
+    name: str
+    headers: list[str] = Field(default_factory=list)
+    rows: list[list] = Field(default_factory=list)        # raw cell values
+    total_row: list = Field(default_factory=list)         # filled by calc
+
+
+class EnergyProjectionRow(BaseModel):
+    item: str
+    kwh: float
+    six_hour_day: float
+
+
+class EquipmentPlan(BaseModel):
+    phase: str             # "Pilot" or "ScaleUp"
+    sections: list[EquipmentSection] = Field(default_factory=list)
+    projection: list[EnergyProjectionRow] = Field(default_factory=list)
+    projection_total_kwh: Optional[float] = None
+    projection_total_six_hour: Optional[float] = None
+
+
+# --------------------------------------------------------------------------- #
+# Budget  (source: Budget sheet)
+# --------------------------------------------------------------------------- #
+class BudgetLineItem(BaseModel):
+    section: str           # "Energy Infrastructure", "Swap Station", etc.
+    item: str
+    details: str = ""
+    quantity: Optional[float] = None
+    unit_price: Optional[float] = None
+    total_price: Optional[float] = None
+
+
+class BudgetSection(BaseModel):
+    name: str
+    items: list[BudgetLineItem] = Field(default_factory=list)
+    total: Optional[float] = None
+
+
+class Budget(BaseModel):
+    sections: list[BudgetSection] = Field(default_factory=list)
+    grand_total: Optional[float] = None
+
+
+# --------------------------------------------------------------------------- #
+# Financial model  (source: Summary + Individual/Agrohub Model sheets)
+# --------------------------------------------------------------------------- #
+class FinancialRow(BaseModel):
+    beneficiary: str       # "Farming Equipment", "Mobility", "SME"
+    quantity: float
+    timeframe_months: float
+    amount_monthly: float
+
+
+class FinancialModel(BaseModel):
+    model_name: str        # "Individual Model - New Equipment", etc.
+    rows: list[FinancialRow] = Field(default_factory=list)
+    total_monthly: Optional[float] = None
+
+
+# --------------------------------------------------------------------------- #
+# Revenue per user  (source: Key Findings — developer-supplied)
+# --------------------------------------------------------------------------- #
+class RevenuePerUserRow(BaseModel):
+    category: str
+    effective_daily_demand_kwh: float
+    effective_annual_demand_kwh: float
+    beneficiaries: int
+    avg_tariff: float
+    daily_revenue_category: float
+    daily_avg_revenue: float
+
+
+# --------------------------------------------------------------------------- #
+# Projected impact  (source: Key Findings impact table)
+# --------------------------------------------------------------------------- #
+class ImpactRow(BaseModel):
+    impact_area: str
+    metric: str
+    projected_outcome: str
+
+
+# --------------------------------------------------------------------------- #
+# Processor / SME distance to minigrid  (source: Key Findings distance table)
+# --------------------------------------------------------------------------- #
+class DistanceRow(BaseModel):
+    name: str
+    site_lat: Optional[float] = None
+    site_long: Optional[float] = None
+    minigrid_gps: str = ""
+    distance_km: Optional[float] = None
+
+
+# --------------------------------------------------------------------------- #
+# Top-level container
+# --------------------------------------------------------------------------- #
+class PUEReportData(BaseModel):
+    community: CommunityProfile
+    minigrid: EnergySystemSpec = Field(default_factory=EnergySystemSpec)
+    microgrid: EnergySystemSpec = Field(default_factory=EnergySystemSpec)
+    interviews: InterviewCounts
+    farmers: FarmerAnalysis
+    processors: ProcessorAnalysis
+    mobility: MobilityAnalysis
+    sme: SMEAnalysis
+    equipment_pilot: EquipmentPlan
+    equipment_scaleup: EquipmentPlan
+    budget: Budget
+    financial_models: list[FinancialModel] = Field(default_factory=list)
+    revenue_per_user: list[RevenuePerUserRow] = Field(default_factory=list)
+    projected_impact: list[ImpactRow] = Field(default_factory=list)
+    processor_distances: list[DistanceRow] = Field(default_factory=list)
+
+    # AI-generated prose (filled by the generation chains, not the extractor)
+    narrative_overview: str = ""
+    narrative_demographic: str = ""
+    narrative_processing_insights: str = ""
+
+    # Provenance / QA — issues the extractor flags for human review
+    warnings: list[str] = Field(default_factory=list)
+
+
+# Pydantic v2 forward-ref resolution for the self-referential model.
+EnergySystemSpec.model_rebuild()

pue_report_agent/templates.py

@@ -0,0 +1,499 @@
+"""
+templates.py
+============
+The report sections that are effectively identical across communities. From the
+Jaji/Kwarua Tasha comparison these are byte-for-byte boilerplate aside from the
+community name and the mini-grid developer, so they should NEVER be sent to an
+LLM — that only risks hallucination and wastes tokens. They are stored as
+format strings and filled deterministically.
+
+If a future report needs to vary one of these, lift it out into the schema and
+add a generation chain for it. Until then, keep it here.
+"""
+
+INTRODUCTION = {
+    "lead": "This study evaluates the needs, viability, profitability, "
+    "implementation, and long-term sustainability of Productive Use of Energy "
+    "(PUE) investments in {community} community. The assessment employed a "
+    "rigorous methodology that combined desktop research, survey design, "
+    "field-based needs assessments, equipment design, financial modeling, and "
+    "project management. Key inputs were provided by the Distributed Renewable "
+    "Energy Enhancement Facility (DREEF), {developer} (the mini-grid "
+    "developer), the PUE team and local community leaders. These contributions "
+    "included technical data, funding support, and facilitation of access to "
+    "community stakeholders and proposed beneficiaries.",
+    "objectives_lead": "The specific objectives of the study were to:",
+    "objectives": [
+        "Identify potential PUE users, their production/processing capacity, "
+        "expenses spent on fossil fuel and their power capacity requirements.",
+        "Assess the socio-economic and commercial viability of PUE "
+        "opportunities.",
+        "Propose tailored PUE solutions.",
+        "Evaluate users' willingness to switch from fossil fuels to "
+        "energy-efficient PUE equipment and to connect to the proposed "
+        "mini-grid for increased productivity.",
+        "Develop an implementation plan for deploying these solutions in the "
+        "community.",
+    ],
+    "closing": "This report provides actionable insights to guide the design "
+    "and deployment of productive use of energy technologies, strengthen rural "
+    "enterprises, and align with Nigeria's broader development priorities, "
+    "while contributing to the achievement of the Sustainable Development "
+    "Goals (SDGs).",
+}
+
+ABOUT_CONTRACTOR = {
+    "body": "This report is carried out by the PUE team of DREEF with "
+    "collaboration from other key expert teams, namely the Technical team, "
+    "Legal team, Financial team, Procurement team, and ESG team.",
+    "link_lead": "For more detailed information about DREEF, kindly click ",
+    "link_text": "HERE",
+    "link_url": "https://dreef.org/",
+    "link_tail": ".",
+}
+
+METHODOLOGY = """\
+A desktop review and gap analysis was conducted to establish baseline \
+information on the community and its mini-grid development prospects. This \
+included assessments of energy demand, household demographics, existing energy \
+sources, environmental and infrastructural factors, financial viability, and \
+regulatory frameworks. Where information was lacking, gaps were identified for \
+follow-up during fieldwork."""
+
+# Risk register — identical across both reviewed reports.
+RISKS_IDENTIFIED = [
+    ("Low Equipment Adoption", "Users may be unwilling to switch from manual or diesel-powered methods due to habit or cost fears."),
+    ("Machine Downtime", "Equipment may break down frequently due to poor maintenance, improper use, or lack of spare parts."),
+    ("Electricity Reliability", "Mini-grid overload or poor solar sizing could affect equipment performance or user satisfaction."),
+    ("Theft and Vandalism", "Equipment, batteries, or solar panels may be stolen or damaged, especially at night or in isolated areas."),
+    ("Lack of Operator Skills", "Improper usage may cause damage or reduce equipment lifespan."),
+    ("Financial Default", "Operators may default on payment models (lease-to-own, usage fees, subscriptions)."),
+    ("Cooperative Failure", "Poor management or conflicts can collapse cooperatives managing shared equipment."),
+    ("Climate Disruptions", "Heavy rains or flooding may affect logistics, deployment schedules, or equipment use."),
+    ("Community Resistance", "Resistance to cooperative models or shared infrastructure from individuals preferring personal ownership."),
+]
+
+MITIGATION_MEASURES = [
+    ("Low Equipment Adoption", "Community sensitization sessions before deployment; early pilot demonstrations with lead users; flexible financing (pay-as-you-use or lease-to-own)."),
+    ("Machine Downtime", "Operator and technician training prior to handover; preventive maintenance schedules; spare parts kits stored locally; equipment logbooks for tracking faults."),
+    ("Electricity Reliability", "System design includes buffer for peak loads; load staggering strategy; battery banks and backup generation in hybrid systems."),
+    ("Theft and Vandalism", "Secure installation (anchor bolts, enclosures); community-led equipment protection committees; asset insurance for high-value machines."),
+    ("Lack of Operator Skills", "Pre-deployment technical training; step-by-step visual SOPs; on-call technical support; quarterly refresher training."),
+    ("Financial Default", "Equipment usage tied to cooperative performance; usage monitoring via IoT; group guarantees or staggered asset handover; revenue-based repayment models."),
+    ("Cooperative Failure", "External facilitation and capacity-building support for 12 months; strong bylaws and conflict resolution frameworks; monthly governance reviews."),
+    ("Climate Disruptions", "Site selection considers drainage and elevation; weather-resistant installations; deployment flexibility during wet season."),
+    ("Community Resistance", "Choice between individual and cooperative models; pilots to test both models; transparent beneficiary selection and inclusive engagement."),
+]
+
+KPIS = [
+    ("Energy Utilization", "kWh consumed per equipment category (daily/monthly)", "Monthly"),
+    ("Energy Utilization", "Peak load vs average load per site", "Monthly"),
+    ("Operational", "Machine uptime and downtime logs (hrs/month)", "Weekly"),
+    ("Operational", "Frequency of maintenance or repairs", "Monthly"),
+    ("Operational", "Processing rate and quantity", "Daily"),
+    ("Economic Impact", "Increase in monthly revenue per processor (₦)", "Quarterly"),
+    ("Economic Impact", "Monthly fuel savings for e-mobility and agro-processors (₦)", "Monthly"),
+    ("Social Impact", "Number of jobs created (technicians, operators, riders)", "Quarterly"),
+    ("Social Impact", "Number of women/youths trained and engaged", "Quarterly"),
+    ("Adoption", "Number of active PUE users", "Monthly"),
+    ("Adoption", "Number of cooperative members enrolled", "Monthly"),
+]
+
+SDGS = [
+    ("SDG 7", "Affordable and Clean Energy", "Deployment of solar mini-grids and reduction in fossil fuel usage"),
+    ("SDG 8", "Decent Work and Economic Growth", "Job creation and promotion of local agro-based industries"),
+    ("SDG 5", "Gender Equality", "Inclusion of women in employment and entrepreneurial roles"),
+]
+
+IMPLEMENTATION_MODELS = [
+    ("Individual Model - New Equipment", "Beneficiaries lease newly procured equipment individually on a lease-to-own basis. Each beneficiary is solely responsible for repayment and eventual ownership."),
+    ("Individual Model - Retrofit", "Existing fossil-fuel equipment is retrofitted to electric power. Beneficiaries pay for the upgrade in installments over the loan repayment period."),
+    ("Agrohub Model", "A shared agricultural hub is established; beneficiaries collectively lease and manage the equipment as a cooperative under a lease-to-own arrangement."),
+    ("Hybrid Model - New Equipment", "A shared hub used by farmer cooperatives (collective lease) and individual agroprocessors (individual lease)."),
+    ("Agrohub Model + Grant", "As the Agrohub Model, but a grant covers the cost of constructing the hub structure, reducing the financial burden on beneficiaries."),
+]
+
+AI_DISCLOSURE = {
+    "intro": [
+        "In the preparation of this report, Artificial Intelligence (AI) was "
+        "applied primarily as a language support and structuring tool. AI was "
+        "used to improve the clarity, readability, and grammatical arrangement "
+        "of the document to ensure that the information presented was coherent "
+        "and professionally communicated.",
+        "It is important to emphasize that the substantive content of the "
+        "report was not generated by AI. The data and insights were drawn from "
+        "multiple reliable sources, including:",
+    ],
+    "sources": [
+        ("Field Data", "Primary information collected through surveys, "
+         "assessments, and stakeholder engagements."),
+        ("Recommendations", "Developed based on the experience and expertise "
+         "of subject matter specialists."),
+        ("Budget Estimates", "Sourced directly from Original Equipment "
+         "Manufacturers (OEMs)."),
+        ("Financial Models", "Designed and validated by the financial team."),
+        ("Technical Inputs", "Provided by the technical team with "
+         "sector-specific knowledge."),
+    ],
+    "closing": "AI therefore played a supporting role in enhancing the "
+    "presentation of information, while the core knowledge, data, and analysis "
+    "were derived from fieldwork, expert judgment, and technical and financial "
+    "teams.",
+}
+
+
+def fill_intro(community: str, developer: str = "the mini-grid developer") -> str:
+    return INTRODUCTION.format(community=community, developer=developer)
+
+
+# =========================================================================== #
+#  TEMPLATE-FAITHFUL BOILERPLATE  (verbatim from the Akotogbo PUE template)
+#  These are the sections that are identical across communities. Only the
+#  {community} / {developer} tokens vary. Everything else renders as-is so the
+#  agent's output matches the reference template's tone and wording exactly.
+# =========================================================================== #
+
+TITLE_BLOCK = {
+    "title": "{community_upper} PRODUCTIVE USE OF ENERGY REPORT",
+    "subtitle_lines": [
+        "Presented by the",
+        "Productive Use of Energy Team",
+        "of",
+        "Distributed Renewable Energy Enhancement Facility",
+    ],
+}
+
+METHODOLOGY_HEADING = ("Desktop review, Gap Analysis of Preliminary "
+                       "information and field management activities")
+
+ENERGY_SUBSTITUTION = [  # Table 3 — Use Case / Current Source / Replacement
+    ("Household lighting", "Kerosene lamps, petrol generators",
+     "Solar electricity"),
+    ("Grinding (cassava); Digesting (Oilpalm)", "Diesel/petrol engines",
+     "PUE machines"),
+    ("SME", "Small petrol generators", "Reliable solar mini-grid power"),
+    ("Mobility", "Petrol powered two-wheelers", "Electric powered two-wheelers"),
+]
+
+# --- Detailed Pilot Infrastructure Specifications (boilerplate prose) ------- #
+AGROHUB_SPEC_INTRO = (
+    "Each AgroHub functions as a centralized processing facility equipped with "
+    "electric-powered machinery tailored to the specific crop value chains. "
+    "The hubs will be:")
+AGROHUB_SPEC_BULLETS = [
+    "Owned by the SPV",
+    "Managed by the cooperative",
+    "Powered by a stand-alone system",
+    "Modular, allowing expansion to accommodate additional machines or "
+    "processing lines during scale-up phases.",
+]
+LAND_BUILDING_LAYOUT = [
+    "Total Land Area: One plot = 15m x 30m = 450m²",
+    "Sunbread size — External Dimensions: 10ft by 10ft container",
+    "Internal Floor Area (Inside): 2.9 m × 2.9 m ≈ 8.41 m²",
+    "Panel Land Size: Half plot of land = 15m x 15m = 225m²",
+    "Agrohub — Pilot Hub Facility: 3.03m x 3.03m",
+]
+INFRA_LAYOUT_TABLE = [  # Table: Pilot Phase Layout – IoT Enabled (indicative)
+    ("Primary Processing Machine (e.g. grater/mill)", "0.7m x 1.5m", "1.05",
+     "Power: ~5.5 kW; IoT: RPM, vibration, energy, temp sensors; mounted near "
+     "motor/hopper."),
+    ("Secondary Processing Machine (e.g. presser/polisher)", "0.8m × 1.5m", "1.2",
+     "Power: ~3.5 kW; IoT: throughput, motor temperature, load sensors."),
+]
+STRUCTURAL_FEATURES = [
+    "Structural Features: Reinforced concrete slab (150–250 mm depending on wet "
+    "zone), oil-resistant epoxy flooring, graded to drains with oil "
+    "interceptors, silt traps, and stainless-steel piping.",
+    "Roof: Steel truss with long-span metal sheeting, insulation, and ridge "
+    "vents for heat and humidity removal.",
+    "Electrical: 3-phase distribution rated ≥ 30 kW with surge protection, "
+    "per-machine breakers, emergency stop buttons, and IoT energy meters.",
+    "Access & Vehicle Movement: Loading bay 8 m × 3 m for trucks and trailers.",
+]
+
+COOP_GOVERNANCE = [  # Table — Structure / Description
+    ("Cooperative Ownership",
+     "Registered multipurpose cooperative owns the AgroHub asset"),
+    ("Management Committee",
+     "5-person committee: Chair, Secretary, Treasurer, O&M Rep, Machine "
+     "Operator Supervisor"),
+    ("Usage Fee System", "Pay-per-use and revenue-share model (₦/kg and % per "
+     "batch)"),
+    ("Revenue Use", "Split between Lease repayment, maintenance fund, "
+     "cooperative savings, machine operator salaries"),
+    ("Operation Hours", "8am – 6pm daily (with booking slots to avoid "
+     "congestion)"),
+    ("Record-Keeping", "Daily usage logs, financial records, machine servicing "
+     "checklist"),
+    ("Dispute Resolution", "Bylaws + local mediation structure for cooperative "
+     "members"),
+]
+
+SAFETY_COMPLIANCE = [  # Table — Aspect / Implementation
+    ("Fire Safety", "1 fire extinguisher + 1 fire blanket + sand bucket per hub"),
+    ("Machine Safety", "Emergency stop buttons, operator training, use of "
+     "gloves & PPE"),
+    ("Electrical Safety", "Grounding of machines, surge protectors, ELCBs, "
+     "visible warning signs"),
+    ("Public Health", "Regular cleaning, pest-proofing, first aid kit on site"),
+    ("Noise Control", "Machines installed with dampeners; zoning of quiet vs. "
+     "loud areas"),
+]
+SECURITY_FEATURES = [
+    "Fenced Compound (block wall or wire mesh)",
+    "Night Security Personnel (optional)",
+    "Solar-powered floodlights",
+    "Inventory Ledger for Inputs and Outputs",
+]
+FIGURE_AGROHUB = "Agrohub Station"
+
+# --- Financial Model: the implementation-model catalogue (Table 43) -------- #
+IMPLEMENTATION_MODELS_FULL = [
+    ("Individual Model - New Equipment",
+     "Under this model, beneficiaries lease newly procured equipment "
+     "individually on a lease-to-own basis. Each beneficiary is solely "
+     "responsible for repayment and eventual ownership of the equipment."),
+    ("Individual Model - Retrofit",
+     "Existing beneficiary equipment powered by fossil fuels is retrofitted to "
+     "electric-powered systems. Beneficiaries pay for the upgrade in "
+     "installments over the agreed loan repayment period."),
+    ("Agrohub Model",
+     "An agricultural hub is established within the community, equipped with "
+     "shared agro-processing machinery. Beneficiaries collectively lease and "
+     "manage the equipment as a cooperative, operating under a lease-to-own "
+     "arrangement."),
+    ("Hybrid Model - New Equipment",
+     "A shared agricultural hub used by two beneficiary sectors: Farmer "
+     "Cooperatives lease new Agrohub equipment collectively on a lease-to-own "
+     "basis; Agroprocessors lease new equipment individually on a lease-to-own "
+     "basis."),
+    ("Hybrid Model - New Equipment + Retrofit",
+     "As the Hybrid Model, but agroprocessors have existing fossil-fuel "
+     "equipment retrofitted to electric and pay for the upgrade over the loan "
+     "period."),
+    ("Agrohub Model + Grant",
+     "As the Agrohub Model, but a grant covers the cost of constructing the "
+     "Agrohub structure, reducing the burden on beneficiaries."),
+    ("Hybrid Model - New Equipment + Grant",
+     "As the Hybrid Model (New Equipment), but a grant covers the Agrohub "
+     "structure while beneficiaries keep lease-to-own payments for equipment."),
+    ("Hybrid Model - New Equipment + Retrofit + Grant",
+     "As the Hybrid Model (New Equipment + Retrofit), with a grant covering the "
+     "Agrohub structure for both cooperatives and individual agroprocessors."),
+]
+
+IMPLEMENTATION_PLAN = [  # Table 48 — S/N, Title, Responsibility, Duration, Timeline
+    ("1", "SPV selection", "Procurement, PUE team", "2 weeks", "Week 1 - 2"),
+    ("2", "Contract Signing", "Legal and PUE team", "2 weeks", "Week 3 - 4"),
+    ("3", "Land Engagement with Community",
+     "SPV, Minigrid Developer and PUE team", "2 weeks", "Week 4 - 5"),
+    ("4", "Project Design",
+     "Minigrid developer, SPV, OEM, IOT, Civil engineer and PUE team",
+     "2 weeks", "Week 6 - 7"),
+    ("5", "Submission of Budgets", "SPV, procurement and PUE team", "1 week",
+     "Week 8"),
+    ("6", "First Payment Made", "SPV, Procurement team, PUE team", "2 weeks",
+     "Week 9 - 10"),
+    ("7", "Account Setup", "SPV, Funder firm", "2 weeks", "Week 11 - 12"),
+    ("8", "Mobilization", "SPV and PUE team", "6 weeks", "Week 13 - 19"),
+    ("9", "Transportation, Installation and Commissioning",
+     "SPV and PUE team", "2 weeks", "Week 20 - 21"),
+    ("10", "Monitoring and Evaluation",
+     "SPV, Financial team and PUE team", "Every Quarter", "Week 25 onward"),
+]
+
+IMPLEMENTATION_PLAN_INTRO = (
+    "The implementation for the {community} PUE initiative will take a minimum "
+    "of 21 weeks (5 months and 1 week) from SPV selection to PUE installation, "
+    "testing and commissioning. The PUE implementation for the individual "
+    "deployment model will follow the process below.")
+
+# --- Conditions for Scaleup (verbatim boilerplate, structured) -------------- #
+SCALEUP_INTRO = ("Below are the key metrics (KPIs) the community must attain "
+                 "before we \u201cactivate\u201d the move from Pilot to Scale-up.")
+
+SCALEUP_SECTIONS = [
+    ("Financial & Repayment Metrics (Lease-to-Own triggers)", [
+        ("Portfolio On-Time Repayment Rate (core trigger)", [
+            "Target: \u2265 95% on-time repayment for 3 consecutive months",
+            "Definition: % of expected monthly repayments received by due date",
+            "Why it matters: proves discipline + bankability"]),
+        ("Portfolio at Risk (PAR) \u2013 early delinquency control", [
+            "PAR 30 (payments 30+ days late): Target \u2264 5%",
+            "PAR 60: Target \u2264 2%",
+            "Why it matters: if PAR rises during pilot, scaling multiplies "
+            "defaults."]),
+        ("Collections Coverage of Operating Costs (hub sustainability)", [
+            "Target: Collections cover 100% of operators\u2019 wages, routine "
+            "maintenance/spares, insurance allocations, admin/collections costs",
+            "Threshold: OPEX Coverage Ratio \u2265 1.0 for 3 straight months"]),
+        ("Minimum Monthly Collections Threshold", [
+            "Achieve \u2265 90% of expected monthly inflow for 3 consecutive "
+            "months (thresholds derived from the Monthly Revenue tables above)."]),
+        ("Reserve Fund Build", [
+            "Maintain a Maintenance & Replacement Reserve \u2265 2 months of "
+            "routine O&M cost OR \u2265 5% of monthly collections, whichever is "
+            "higher",
+            "Evidence: separate wallet/account + monthly statement"]),
+    ]),
+    ("Operational & Technical Metrics (Proof the hub can run)", [
+        ("Asset Uptime (processing + charging + SME loads)", [
+            "Target: \u2265 90\u201395% uptime during planned operational hours",
+            "Evidence: IoT runtime logs + operator downtime register"]),
+        ("Energy System Reliability", [
+            "Target: \u2265 95% availability of the modular solar system",
+            "Evidence: inverter logs, battery cycles, fault logs"]),
+        ("Utilization Threshold (demand proof)", [
+            "Processing utilization \u2265 60% of available hours for 8 "
+            "consecutive weeks, or a waiting list \u2265 20% of slots weekly"]),
+        ("Maintenance Compliance (culture trigger)", [
+            "Target: 100% daily checks + \u2265 90% weekly preventive "
+            "maintenance tasks completed",
+            "Evidence: signed checklists + monthly maintenance audit"]),
+    ]),
+    ("Governance & Accountability Metrics", [
+        ("Operating Charter Compliance", [
+            "Target: zero \u201coff-book\u201d transactions for 90 days",
+            "Evidence: receipts, booking system, reconciliation reports"]),
+        ("Dispute Resolution Performance", [
+            "Target: \u2265 90% of grievances resolved within 7 days",
+            "Evidence: grievance log with timestamps + outcomes"]),
+        ("Governance Discipline", [
+            "Hub Management Committee meets monthly with minutes, financial "
+            "summary review, and downtime/maintenance report review",
+            "Evidence: signed minutes + action tracker"]),
+    ]),
+    ("Data & IoT Metrics", [
+        ("Data Completeness", [
+            "Target: \u2265 90% completeness across runtime, energy (kWh), "
+            "booking/throughput records, payments/receipts",
+            "Evidence: monthly dashboard export + spot-checks"]),
+        ("Data Integrity (anti-fraud)", [
+            "Variance between recorded throughput vs runtime vs energy draw "
+            "stays within an agreed tolerance (e.g. \u00b110\u201315%)",
+            "Evidence: audit comparisons"]),
+    ]),
+    ("Market & Value Chain Metrics", [
+        ("Market Pull / Offtake Proof", [
+            "At least one of: signed buyer agreement / offtake MoU; repeat bulk "
+            "buyers with documented purchase history; 3-month processor sales "
+            "growth trend"]),
+        ("Quality Standard Compliance", [
+            "Consistent quality specs (quality, hygiene, packaging) with "
+            "\u2264 5% rejection/complaints",
+            "Evidence: buyer feedback + QC log"]),
+    ]),
+    ("Inclusion & Social Metrics", [
+        ("Participation Targets (minimum inclusion triggers)", [
+            "\u2265 25% of hub processing slots allocated to women/youth "
+            "beneficiaries, or a clear step-up plan toward that",
+            "At least 1 female in a financial-control role (cashier/admin/"
+            "treasurer) or deputy role",
+            "Evidence: booking records + committee roster"]),
+    ]),
+]
+
+SCALEUP_GATE = [
+    "Repayment performance: On-time repayment \u226595% for 3 months; "
+    "PAR30 \u22645%",
+    "Collections threshold: \u226590% of expected monthly inflow for 3 months",
+    "Operational reliability: uptime \u226590\u201395% and energy availability "
+    "\u226595%",
+    "Demand proof: utilization \u226560% for 8 weeks or waiting list \u226520% "
+    "of slots weekly",
+    "Governance proof: zero off-book transactions + grievances resolved within "
+    "7 days",
+    "Data proof: \u226590% completeness and auditable logs",
+]
+
+MER_INTRO = (
+    "To ensure the effectiveness, efficiency, and sustainability of the PUE "
+    "intervention in {community}, a structured Monitoring, Evaluation, and "
+    "Reporting (MER) framework will be deployed. This system will track energy "
+    "usage, equipment performance, productivity outcomes, and community impact, "
+    "while integrating mechanisms for continuous feedback and improvement.")
+
+DATA_TOOLS = [  # Table — Tool / Purpose / Managed By
+    ("IoT Smart Meters", "Track real-time energy consumption & machine uptime",
+     "Technical Partner / SPV"),
+    ("Mobile Enumerator Forms", "Collect monthly performance and business data",
+     "PUE team"),
+    ("WhatsApp / SMS Survey Tools", "Collect qualitative feedback from "
+     "end-users", "Various stakeholders"),
+    ("Equipment Logbooks", "Record hours of use and faults", "SPV"),
+    ("Digital Dashboard (central)", "Aggregates all KPIs and generates "
+     "automated reports", "DI Team"),
+]
+
+FEEDBACK_LOOPS = [  # Table — S/N, Item, Who, Frequency, Purpose
+    ("1", "Operator Feedback Sessions", "Operator and cooperative member",
+     "Monthly", "Discuss challenges, machine performance, and suggestions"),
+    ("2", "Rider Survey Check-ins", "E-mobility operators and association",
+     "Bi-Monthly", "Assess performance, route efficiency, battery swap "
+     "satisfaction, and fuel savings"),
+    ("3", "Performance Alerts", "All IoT enabled devices", "Instant",
+     "Flag high downtime, abnormal consumption, or device malfunctions"),
+    ("4", "Grievance Redress System", "All beneficiaries", "Instant",
+     "Mobile/WhatsApp hotline for complaints or service requests in real time"),
+    ("5", "Quarterly MEL Reports", "Shared with stakeholders", "Quarterly",
+     "Key insights, deviations, and corrective actions"),
+]
+
+PROJECTED_IMPACT_DEFAULT = [  # Table 54 — used if the sheet has none
+    ("Processing Output", "Tons/bags processed monthly", "+250\u2013350% increase"),
+    ("Average Processor Income", "\u20a6 / month", "+100\u2013200% growth"),
+    ("E-Mobility Operators", "Monthly Savings", "\u20a640,000\u2013\u20a6100,000"),
+    ("Mini-grid Utilization", "kWh / day increase", "+400\u2013500%"),
+    ("CO\u2082 Emission Reduction", "Estimated % decrease", "25\u201340%"),
+    ("Employment", "Jobs created", "120+"),
+    ("Women Beneficiaries", "% of total beneficiaries", "Over 45%"),
+]
+
+KEY_CHALLENGES = [  # Table 56 — Lesson Learned / Recommended Best Practice
+    ("Inexperienced enumerators from the database network",
+     "Develop a tiered enumerator training program (digital LMS + field "
+     "orientation); add supervisory review layers; run competency tests before "
+     "deployment; maintain a certified \u201cgold pool\u201d for sensitive PUE "
+     "projects."),
+    ("Inconsistent data sources",
+     "Establish a standardized data-collection template; triangulate each data "
+     "point against \u22652 sources; use a validation checklist; centralize "
+     "data in a version-controlled repository."),
+    ("Limited literacy and data recording among processors",
+     "Simplify questionnaires with visual aids; use assisted interviews; "
+     "provide basic recordkeeping training; pilot digital record tools."),
+    ("Delayed responses from OEMs",
+     "Prequalify a roster of responsive OEMs with SLAs; use framework "
+     "agreements; assign a vendor liaison; tie penalties/incentives to "
+     "timeliness."),
+    ("Partial supplier responses",
+     "Issue structured RFQ templates; reject incomplete submissions; establish "
+     "preferred-supplier partnerships; require after-sales commitments."),
+    ("Data accuracy and completeness",
+     "Deploy real-time tools with GPS + timestamp; automate validation/outlier "
+     "checks; require double-entry verification; conduct spot checks."),
+    ("Unrealistic delivery timeline",
+     "Create a standard delivery timeline; build 20\u201330% buffer periods; "
+     "confirm realistic OEM lead times early; use Gantt planning."),
+]
+
+FORECASTED_CHALLENGES = [  # Table 57 — Lesson Learned / Recommended Best Practice
+    ("Overloading of electric motors on single-phase supply above 2\u20133 HP",
+     "Use three-phase power systems for all induction motors"),
+    ("Mini-grid disruption from startup surge currents",
+     "Equip all induction-motor machines with variable speed drives or soft "
+     "starters"),
+    ("Reliability of mini-grid power supply",
+     "Schedule PUE operations during peak solar generation hours"),
+    ("Insufficient mini-grid capacity for additional agro-processors",
+     "Coordinate with developers to confirm grid compatibility and capacity "
+     "before deployment"),
+    ("Inconsistent year-round equipment use",
+     "Introduce smaller PUE appliances (wet milling, cold storage) to stabilise "
+     "off-peak demand"),
+    ("Need to extend the mini-grid network to reach all processors",
+     "Reassess grid design with developers to incorporate PUE integration"),
+    ("Risk of equipment theft",
+     "Allocate security resources, especially for centralised agro hubs"),
+]

pue_report_agent/validate.py

@@ -0,0 +1,97 @@
+"""
+validate.py
+===========
+Post-extraction sanity checks. These exist because the source spreadsheets are
+hand-maintained and carry known defects (stale template text, totals that don't
+foot, interview counts that disagree between tabs). The agent should surface
+these to a human reviewer rather than silently emitting a wrong report — that
+is exactly how the Kwarua Tasha report ended up internally inconsistent.
+
+Each check appends a human-readable string to `data.warnings`. Nothing here
+mutates the numbers; correction is a human decision.
+"""
+
+from __future__ import annotations
+
+from .schema import PUEReportData
+
+
+def validate(data: PUEReportData) -> PUEReportData:
+    _check_interview_totals(data)
+    _check_sme_consistency(data)
+    _check_budget_foots(data)
+    _check_gender_baseline(data)
+    _check_capacities_present(data)
+    _check_crop_percentages(data)
+    _check_co2_inputs(data)
+    return data
+
+
+def _check_interview_totals(d: PUEReportData) -> None:
+    parts = (d.interviews.farmers + d.interviews.agroprocessors +
+             d.interviews.sme + d.interviews.mobility)
+    if d.interviews.total and parts != d.interviews.total:
+        d.warnings.append(
+            f"Interview total ({d.interviews.total}) != sum of categories "
+            f"({parts}). Reconcile the 'People interviewed' block.")
+
+
+def _check_sme_consistency(d: PUEReportData) -> None:
+    listed = sum(t.count for t in d.sme.types)
+    if d.sme.total and listed and listed != d.sme.total:
+        d.warnings.append(
+            f"SME header total ({d.sme.total}) != sum of SME type counts "
+            f"({listed}). The Kwarua Tasha report had this exact mismatch.")
+    if d.interviews.sme and d.sme.total and d.interviews.sme != d.sme.total:
+        d.warnings.append(
+            f"SME interview count ({d.interviews.sme}) != SME breakdown total "
+            f"({d.sme.total}).")
+
+
+def _check_budget_foots(d: PUEReportData) -> None:
+    for s in d.budget.sections:
+        if s.items and s.total is not None:
+            line_sum = sum(i.total_price or 0 for i in s.items)
+            if line_sum and abs(line_sum - s.total) > 1:
+                d.warnings.append(
+                    f"Budget section '{s.name}': line items sum to "
+                    f"{line_sum:,.0f} but stated total is {s.total:,.0f}.")
+
+
+def _check_gender_baseline(d: PUEReportData) -> None:
+    # The boilerplate 'Inclusion' section hardcodes '34 male vs 7 female';
+    # confirm the real farmer baseline so the generator can substitute it.
+    if d.farmers.male or d.farmers.female:
+        d.warnings.append(
+            f"Farmer gender baseline is {d.farmers.male} male / "
+            f"{d.farmers.female} female. Ensure the Inclusion section uses "
+            f"these figures, not the templated '34 male vs 7 female'.")
+
+
+def _check_capacities_present(d: PUEReportData) -> None:
+    if not d.minigrid.solar_pv:
+        d.warnings.append(
+            "Mini-grid capacity (Solar PV / Battery / Annual Consumption) was "
+            "not supplied. These are developer figures and must be provided "
+            "as an external input; they are not derivable from the survey data.")
+
+
+def _check_co2_inputs(d: PUEReportData) -> None:
+    rows = d.processors.co2_assessment
+    if rows and all(r.annual_fuel_litres is None for r in rows):
+        machines = ", ".join(sorted({r.machine for r in rows}))
+        d.warnings.append(
+            f"CO2 assessment: fuel-powered machines detected ({machines}) but "
+            f"per-machine annual fuel consumption (litres) is not in the sheet, "
+            f"so emissions can't be computed. Supply annual fuel litres to "
+            f"complete the CO2 table (IPCC factors 2.31 petrol / 2.86 diesel).")
+
+
+def _check_crop_percentages(d: PUEReportData) -> None:
+    # Percentages are share-of-households and legitimately exceed 100% in total
+    # (a farmer grows multiple crops), so we only flag individual outliers.
+    for c in d.farmers.crops:
+        if c.percentage > 100:
+            d.warnings.append(
+                f"Crop '{c.crop}' has household share {c.percentage}% > 100%; "
+                f"check the farming-household count.")

requirements.txt

@@ -0,0 +1,15 @@
+# Core extraction + validation (no API key required)
+openpyxl>=3.1
+pydantic>=2.5
+
+# Web app (Hugging Face Space front-end)
+streamlit>=1.40
+
+# LLM narrative generation (agent.py) — currently all narratives use Gemini
+langchain>=0.2
+langchain-core>=0.2
+langchain-google-genai>=1.0
+# langchain-anthropic>=0.1   # uncomment if you switch any chain back to Anthropic
+
+# Optional, for render.py (deterministic .docx output)
+python-docx>=1.1

run.py

@@ -0,0 +1,113 @@
+"""
+run.py
+======
+CLI entry point. Demonstrates the full pipeline and prints a QA summary.
+
+Usage:
+    # Extraction + validation only (no API key needed):
+    python run.py path/to/Master_Sheet.xlsx --no-llm
+
+    # Full run with narratives (requires ANTHROPIC_API_KEY):
+    python run.py path/to/Master_Sheet.xlsx --developer "Green Edge Consortium"
+
+The mini-grid capacities are an external input (developer-supplied, not in the
+survey data). Pass them with --solar-pv / --battery / --annual-consumption, or
+fill them in afterwards on the returned object before rendering.
+"""
+
+from __future__ import annotations
+
+import argparse
+
+from pue_report_agent import extract_master_sheet, validate, recompute
+from pue_report_agent.schema import EnergySystemSpec
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser(description="PUE report builder")
+    ap.add_argument("master_sheet")
+    ap.add_argument("--developer", default="the mini-grid developer")
+    ap.add_argument("--no-llm", action="store_true",
+                    help="skip narrative generation (no API key required)")
+    ap.add_argument("--solar-pv", default="")
+    ap.add_argument("--battery", default="")
+    ap.add_argument("--annual-consumption", default="")
+    ap.add_argument("--date", default="", help="report date for the title page")
+    ap.add_argument("--docx-out", default="",
+                    help="render a template-faithful .docx to this path")
+    ap.add_argument("--json-out", default="",
+                    help="write the full PUEReportData JSON to this path")
+    args = ap.parse_args()
+
+    # 1. Deterministic extraction
+    data = extract_master_sheet(args.master_sheet)
+
+    # 2. Recompute every total from line items (never trust a sheet total)
+    data = recompute(data)
+
+    # 3. External developer-supplied capacity overrides (optional). Merge into
+    #    the already-extracted minigrid so we don't discard the distribution
+    #    metrics / inverter that extraction pulled from Key Findings.
+    if args.solar_pv:
+        data.minigrid.solar_pv = args.solar_pv
+    if args.battery:
+        data.minigrid.battery_storage = args.battery
+    if args.annual_consumption:
+        data.minigrid.annual_consumption = args.annual_consumption
+
+    # 4. Validation / reconciliation
+    data = validate(data)
+
+    # 5. Narratives (optional). All narratives use Gemini.
+    if not args.no_llm:
+        from pue_report_agent import generate_narratives
+        if generate_narratives is None:
+            print("[warn] langchain not installed; skipping narratives.")
+        else:
+            data = generate_narratives(data)
+
+    # 6. QA summary
+    _print_summary(data)
+
+    # 7. Render the template-faithful Word document
+    if args.docx_out:
+        from pue_report_agent.render import render
+        render(data, args.docx_out, developer=args.developer,
+               report_date=args.date)
+        print(f"\nWrote {args.docx_out}")
+
+    if args.json_out:
+        with open(args.json_out, "w") as fh:
+            fh.write(data.model_dump_json(indent=2))
+        print(f"Wrote {args.json_out}")
+
+
+def _print_summary(data) -> None:
+    c = data.community
+    print("=" * 64)
+    print(f" {c.name}  ({c.lga}, {c.state})")
+    print("=" * 64)
+    print(f" Interviewed: {data.interviews.total}  "
+          f"(farmers {data.interviews.farmers}, processors "
+          f"{data.interviews.agroprocessors}, SME {data.interviews.sme}, "
+          f"mobility {data.interviews.mobility})")
+    print(f" Farmers: {data.farmers.male}M / {data.farmers.female}F, "
+          f"{len(data.farmers.crops)} crops")
+    print(f" Processors: {data.processors.male}M / {data.processors.female}F, "
+          f"{len(data.processors.machinery)} machines on record")
+    print(f" SME types: {len(data.sme.types)}   Mobility: {data.mobility.total}")
+    print(f" Pilot energy: {data.equipment_pilot.projection_total_kwh} kWh   "
+          f"ScaleUp: {data.equipment_scaleup.projection_total_kwh} kWh")
+    print(f" Budget grand total: ₦{(data.budget.grand_total or 0):,.0f}")
+    print(f" Financial models: {[m.model_name for m in data.financial_models]}")
+    print()
+    if data.warnings:
+        print(f" ⚠  {len(data.warnings)} item(s) need review:")
+        for w in data.warnings:
+            print(f"    • {w}")
+    else:
+        print(" ✓ no warnings")
+
+
+if __name__ == "__main__":
+    main()