Metadata-Version: 2.4
Name: open-fdd
Version: 4.1.1
Summary: Open-FDD libraries: ECM engineering workbooks plus pandas oracle rules, analytics, and Engineering Findings reporting. Production FDD remains the DataFusion/GHCR stack.
Author-email: Ben Bartling <ben.bartling@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/bbartling/open-fdd
Project-URL: Documentation, https://bbartling.github.io/open-fdd/
Project-URL: Repository, https://github.com/bbartling/open-fdd
Keywords: hvac,ecm,fdd,fault-detection,energy-conservation,building-automation,open-fdd
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: ecm-web
Requires-Dist: fastapi>=0.115; extra == "ecm-web"
Requires-Dist: uvicorn>=0.34; extra == "ecm-web"
Requires-Dist: pydantic<3,>=2.4; extra == "ecm-web"
Provides-Extra: oracle
Requires-Dist: pandas>=2.0.0; extra == "oracle"
Requires-Dist: numpy>=1.26.0; extra == "oracle"
Requires-Dist: pyyaml>=6.0; extra == "oracle"
Provides-Extra: reporting
Requires-Dist: open-fdd[oracle]; extra == "reporting"
Requires-Dist: python-docx>=1.1.0; extra == "reporting"
Requires-Dist: openpyxl>=3.1.0; extra == "reporting"
Requires-Dist: matplotlib>=3.8.0; extra == "reporting"
Requires-Dist: plotly>=5.22.0; extra == "reporting"
Requires-Dist: kaleido>=0.2.1; extra == "reporting"
Provides-Extra: vibe19
Requires-Dist: open-fdd[reporting]; extra == "vibe19"
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"
Requires-Dist: open-fdd[reporting]; extra == "test"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: build>=1.2.0; extra == "dev"
Requires-Dist: twine>=6.0.0; extra == "dev"
Requires-Dist: open-fdd[reporting]; extra == "dev"
Provides-Extra: release
Requires-Dist: build>=1.2.0; extra == "release"
Requires-Dist: twine>=6.0.0; extra == "release"
Dynamic: license-file

# Open-FDD Python package (PyPI)

`open-fdd` (PyPI **4.1+**) ships:

1. **ECM engineering** (`open_fdd.ecm_engineering`) — agent-drivable HVAC spreadsheet workbooks + Python benchmarks.
2. **Pandas oracle** (`open_fdd.rules`, `open_fdd.analytics`, `open_fdd.reporting`) — vibe19 catalog, analytics helpers, Engineering Findings.

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](https://bbartling.github.io/open-fdd/quick-start/docker-ghcr.html), not this wheel.

## Install

```bash
pip install open-fdd                 # ECM only (stdlib)
pip install "open-fdd[oracle]"       # + pandas rules / analytics
pip install "open-fdd[reporting]"    # + Engineering Findings extras
pip install "open-fdd[vibe19]"       # playground meta-extra
```

For the FastAPI ECM example:

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

## Oracle rules (pandas)

```python
from open_fdd.rules import RULES, run_rule
```

## Generate a workbook in a few lines

```python
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.

## Independent benchmark

```python
from open_fdd.ecm_engineering import ECMJob

job = ECMJob("demo")
result = job.calc(
    "fan_affinity",
    design_kw=55.9,
    hours=4100,
    baseline_speed_fraction=0.82,
    proposed_speed_fraction=0.67,
)
```

## CLI

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

## Engineering posture

Prefer measured BAS, utility, TAB, nameplate and manufacturer data over defaults.
Generic chiller `%/°F` methods are screening proxies; manufacturer performance
maps or calibrated EnergyPlus should replace them when stronger estimates are needed.
