| name | audette-energy-data |
| description | Extracts utility bill data from PDF or Excel files in the project folder, validates 12-month concurrent and continuous coverage across all meters, and submits the records to Audette — triggering a re-model. Use this skill when the user wants to compile energy data for a building, extract utility bills, or upload consumption data to Audette. Triggers on: "compile energy data", "extract utility bills", "process energy files", "prepare energy data for [building]", "upload utility data", or "get consumption from bills".
|
| version | 1.0.0 |
| requires | ["audette-mcp"] |
Audette Energy Data
Extract utility bill data from PDFs and Excel files, validate 12-month coverage, and submit to Audette.
Required: Audette MCP
Note: Only electricity, natural_gas, and steam are submitted to Audette. oil and water are captured in the local CSV for reference but the Audette model does not use them.
Pre-flight
Call switch_customer_account with the Audette customer account UID from the system prompt.
This is required before any Audette write operations — omitting it causes HTTP 401.
If no account UID is in the system prompt, call list_customer_accounts and ask the user to select one.
Step 1: Identify the Building
The building UID is in the system prompt if this asset has been linked to Audette.
If not, call list_buildings to find it by name or address, or ask:
"Which building is this utility data for?"
Note the building_model_uid — it's required for submission.
Step 2: Check Existing Utility Data
Call get_building_utility_data with the building_model_uid.
If records already exist, show a summary:
This building already has utility data in Audette:
Electricity: [N] records, [start] to [end]
Natural gas: [N] records, [start] to [end]
Replace all existing data, append new records, or cancel?
If replacing, proceed — the add_building_utility_data call will overwrite.
If appending, note the existing date range so duplicate periods can be flagged in Step 7.
If cancelling, stop here.
Step 3: Scan for Utility Bill Files
Scan the project folder recursively for utility bill files:
- PDFs or Excel files (
.xlsx, .xls) whose names contain: bill, invoice, utility, electric, gas, steam, water, energy, statement
- Any file inside a folder named:
utilities, bills, invoices, energy
List the files found and confirm with the user:
"I found [N] utility bill file(s): [list]. Extract data from all of them?"
If no files found, ask the user to provide the file location or upload bills to the workspace.
Step 4: Extract Data from Files
For each file, use the Read tool (PDFs) or read Excel files directly. A single file may contain multiple months or energy types — extract all as separate rows.
Required Fields
| Field | Notes |
|---|
| Supplier | Utility company name (e.g. "Eversource", "National Grid") |
| Account number | As printed on the bill |
| Energy type | Normalize to: electricity, natural_gas, steam, oil, water, other |
| Start date | Billing period start — YYYY-MM-DD |
| End date | Billing period end — YYYY-MM-DD |
| Consumption | Numeric only |
| Unit | e.g. kWh, therms, ccf, MMBtu, lbs |
| Cost | Total billed, numeric only. Negative for credits. |
| Currency | USD or CAD |
Extraction rules:
- If a field is missing or unreadable, leave it blank — do not guess
- Delivery + supply shown separately → combine into one row with total cost
- Same Supplier + Account + Start + End duplicated → keep first, flag to user
Energy type mapping:
| Bill says | Use |
|---|
| Electric, Electricity, Power | electricity |
| Natural Gas, Gas, NG | natural_gas |
| Steam, District Steam | steam |
| Fuel Oil, Oil, #2 Oil | oil |
| Water, Sewer | water |
Decrypting Encrypted PDFs
If the Read tool fails on a PDF:
pip install pikepdf --break-system-packages
python3 -c "
import pikepdf, sys
src = sys.argv[1]
dst = src.replace('.pdf', '_decrypted.pdf')
pikepdf.open(src, password='').save(dst)
print(f'Decrypted → {dst}')
" "<path_to_locked.pdf>"
Monthly Cost Estimation
If a bill shows a 12-month consumption chart but only the current period's total cost, estimate other months using the blended rate:
rate = current_total_cost / current_period_consumption
estimated_cost = monthly_consumption × rate
Tell the user:
"Monthly costs for [Supplier] were estimated using the blended rate from the current bill ($X.XX/unit). Actual monthly costs may vary."
Step 5: Save Raw CSV
Write all extracted rows to utility-data-<building-slug>-raw.csv using these columns:
Supplier, Account number, Energy type, Start date, End date, Consumption, Unit, Cost, Currency
Step 6: Validate
Run the validation script against the raw CSV:
python3 <skill_base_dir>/scripts/validate_energy_data.py \
--input utility-data-<building-slug>-raw.csv \
--output utility-data-<building-slug>-<YYYY-MM-DD>.csv
The script:
- Normalises units: electricity →
kWh, thermal → GJ
- Checks continuity per meter — fills 1-month gaps via linear regression
- Finds 12-month concurrent window across all meters
- Attempts year-based time-shifting if meters don't naturally overlap
- Exits 0 on PASS (validated CSV written), exits 1 on FAIL
Handling Failures
If the script exits 1, show the failure report verbatim and ask:
"Would you like to remove the failing meter and rerun, or obtain the missing bills and try again?"
Do not proceed to submission until the script exits 0.
Step 7: Confirm Before Submitting
Show the validation summary and ask for confirmation:
Validation passed. Ready to submit to Audette:
Building: [building_name] ([building_model_uid])
Meters: [N]
Period: [start] to [end]
Records: [N] rows
Submitting: electricity, natural_gas, steam only
[oil/water if present]: captured in CSV, not submitted to Audette
Submit?
Step 8: Submit to Audette
Map the validated CSV rows to the MCP format. Only submit rows where Energy type is electricity, natural_gas, or steam.
For each qualifying row:
| CSV field | MCP field | Notes |
|---|
Energy type | utility_type | exact match |
Start date | start_date | YYYY-MM-DD |
End date | end_date | YYYY-MM-DD |
Consumption | energy_consumption | already normalised |
Unit (kWh or GJ) | energy_consumption_unit | lowercase: kwh or gj |
Currency | currency | USD or CAD |
Cost | utility_cost | always pass 0 if unknown — never null/None (see note below) |
Account number | account_number | optional |
Supplier | utility_provider | optional |
Call add_building_utility_data with building_model_uid and the full utility_data array in a single call.
⚠️ utility_cost must always be a number — never null or omitted. Pass 0 when cost is unknown or estimated. Passing null causes the calibration service (SMR) to throw AutoCalibratorError: Unexpected <class 'TypeError'>: cannot unpack non-iterable NoneType object during re-modelling.
The MCP server validates independently and triggers re-modelling on success.
Step 9: Confirmation
Utility data submitted.
Building: [building_name]
Records: [N] submitted ([N] electricity, [N] natural_gas, [N] steam)
Period: [start] to [end]
Re-modelling: triggered — updated carbon plan available shortly
Local CSV saved: utility-data-<building-slug>-<YYYY-MM-DD>.csv
[If oil/water present]: oil/water records saved locally only (not supported by Audette model)
Next steps:
1. Equipment survey → audette-equipment-survey
2. Full report → report
Error Handling
No utility bills found
No utility bill files found in this workspace. Upload bills (PDF or Excel) to the project folder and try again.
MCP validation failure (server rejects submission)
Audette rejected the submission: [error message]. This usually means gaps in coverage or mismatched date ranges. Check the validated CSV and re-run.
Scanned / image PDFs
[filename] appears to be a scanned image — text extraction is not possible. Please use an OCR tool (e.g. Adobe Acrobat, Tesseract) to extract the text first, or retype the data into the CSV template manually.
Rules
- Always call
switch_customer_account before any MCP calls
- Always check existing utility data before submitting
- Never submit without user confirmation (Step 7)
- Never fabricate consumption values — if extraction fails, tell the user
- Always flag estimated costs clearly
- Always save a local CSV regardless of submission outcome — it is the audit trail
oil and water records go into the CSV but are silently excluded from the MCP payload- The MCP validates on its own — if it rejects, report the error verbatim
utility_cost must always be a number — never null or omitted. Pass 0 when cost is unknown or when submitting estimates. Passing null causes AutoCalibratorError: cannot unpack non-iterable NoneType object during re-modelling.
