Open-FDD Python package (PyPI)

open-fdd ships AI-agent RCx/FDD reporting and ECM workbooks. ECM guide: https://bbartling.github.io/open-fdd/ecm/

AI agent report — open-fdd-anomaly report ... --compile from mapped roles. Not Railway-only: a local CSV plus column map, a Railway or self-hosted Open-FDD central (agent-supplied reader), or a future vendor API. Default title Open-FDD AI Agent Report. --title and --location are optional.
ECM engineering (open_fdd.ecm_engineering) — agent-drivable HVAC spreadsheet workbooks + Python benchmarks.
Pandas oracle (open_fdd.rules, open_fdd.analytics, open_fdd.reporting) — cookbook catalog, analytics helpers, Engineering Findings.

Works with any AI agent that can read markdown skills and run the PyPI CLI. Skill source of truth: openfdd_agent_spec/skills/ (./scripts/openfdd_install_agent_skills.sh --sync).

AI agent reporting can consume FDD and analytics that DataFusion SQL already ran on an Open-FDD instance (Railway or self-hosted), or crunch the same mapped roles locally with the PyPI pandas oracle on a CSV. Either path is valid: not compute-only, and not Railway-only.

Why it exists: agents put industry-method calcs into Excel for human audit, then optionally compare honesty against EnergyPlus — see Purpose: Excel + EnergyPlus.

The ECM API fills the same workbook input cells a human engineer would fill. It does not replace the visible spreadsheet calculations.

Production FDD (DataFusion SQL fault detection) lives in the GHCR container stack, not this wheel.

Product freeze / upsell: Engineer upsell brief — customers see ECM via PyPI → open-fdd, not vibe tip churn.

Build handoff / golden example: OPENFDD_AGENT_ECM_HANDOFF · packaged workbook in-repo under open_fdd/ecm_engineering/examples/liberty_dual_ahu/ECM_FULL_PARITY.xlsx.

Community review — help wanted

Field engineers and M&V reviewers: please help validate the ECM catalog. Full module list: Engineering calcs. Ongoing coordination: GitHub #985 (help wanted). Docs-only updates do not close #985 — it stays the community call-for-review.

Review formula accuracy, units, assumptions, workbook clarity, and whether screening methods are labeled appropriately. Even one module or list_calculators() entry helps.

Minimal check

pip install open-fdd
open-fdd-ecm calculators
open-fdd-ecm demo --out ./Demo_ECMs.xlsx

From a repo clone: pip install -e . then pytest tests/ecm/ -q --tb=no.

Feedback

Comment on #985 (module name, issue, reference or fix).
Open a PR for formula, doc, test, or workbook changes.
Share anonymized inputs + expected results for regression tests.

Do not include confidential client or building information in GitHub threads.

Install

pip install open-fdd                 # ECM only (openpyxl)
pip install "open-fdd[oracle]"       # + pandas rules
pip install "open-fdd[analytics]"    # + analytics helpers (same as oracle)
pip install "open-fdd[reporting]"    # + Engineering Findings extras
pip install "open-fdd[anomaly]"      # + offline anomaly screening (STL, Isolation Forest)

For the FastAPI ECM example:

pip install "open-fdd[ecm-web]"

Oracle rules (pandas)

from open_fdd.rules import RULES, run_rule

Generate a workbook in a few lines

from open_fdd.ecm_engineering import ECMJob

job = (
    ECMJob("Lincoln Middle School")
    .set_global(
        area_ft2=85000,
        electric_rate=0.145,
        gas_rate=0.92,
    )
    .add_ecm(
        "static_pressure_reset",
        fan_kw=55.9,
        hours=4100,
        baseline_speed=0.82,
        proposed_speed=0.67,
    )
    .add_ecm(
        "boiler_reset",
        base_therms=48000,
        base_eff=0.86,
        prop_eff=0.92,
    )
)

job.save("Lincoln_Middle_School_ECMs.xlsx")

The resulting XLSX contains the engineering inputs and formulas for human review.

Module names vs calculators

from open_fdd.ecm_engineering import list_ecm_modules, list_calculators

list_ecm_modules()   # names accepted by add_ecm (aliases included)
list_calculators()   # independent Python benchmarks (job.calc), not sheet names

CLI

open-fdd-ecm calculators
open-fdd-ecm demo --out Demo_ECMs.xlsx

Anomaly screening

Offline AHU IO screen of a device folder (history_wide.csv + column_map.json). Z-score and MAD are SQL-portable rolling stats. STL and Isolation Forest are Python-only (open-fdd[anomaly]).

open-fdd-anomaly screen ./AHU_1 --out ./anomaly_out
# defaults: --top-n 5 --max-days 10 --methods zscore,mad,stl,iforest

# Single AHU FDD/RCx PDF. Only this CLI; no build_april_report.py or other local runner.
# History is mapped roles: local CSV+map, Railway or self-hosted Open-FDD, or a future vendor API.
# --compile writes report.pdf when typst is on PATH.
# --month filters every plot. --week pins the RCx window (YYYY-MM-DD, 7 days).
# Web OAT: mapped column, CSV (web_oa_t reindexed onto the BAS clock), or fetch.
# Economizer scatter: x = OAT−RAT, y = MAT−RAT, bottom-left quadrant only.
# build_economizer_delta_points (alias economizer_delta_frame).
open-fdd-anomaly report ./AHU_1 --out ./ahu1_report --month 2026-06 --compile
open-fdd-anomaly report ./AHU_1 --out ./ahu1_report --month 2026-06 --web-oat ./weather.csv --compile
# April folder (8640 rows @ 5 min). Do not fetch this in CI.
open-fdd-anomaly report ./AHU_1 --out ./april_report --month 2026-04 \
  --web-oat ./open_meteo_april.csv --week 2026-04-06 --compile
open-fdd-anomaly report ./BUILDING --scope building --out ./bldg_report --compile