Metadata-Version: 2.4
Name: open-fdd
Version: 2.0.9
Summary: Fault Detection and Diagnostics for HVAC systems — config-driven, pandas-based
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,fdd,fault-detection,building-automation,pandas,brick
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.9
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: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas
Requires-Dist: pyyaml
Provides-Extra: dev
Requires-Dist: aiohttp; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: black[jupyter]; extra == "dev"
Requires-Dist: pre-commit; extra == "dev"
Requires-Dist: httpx; extra == "dev"
Requires-Dist: psycopg2-binary; extra == "dev"
Requires-Dist: requests; extra == "dev"
Requires-Dist: pydantic-settings; extra == "dev"
Requires-Dist: fastapi; extra == "dev"
Requires-Dist: uvicorn[standard]; extra == "dev"
Requires-Dist: python-multipart; extra == "dev"
Requires-Dist: rdflib<8,>=7.5.0; extra == "dev"
Requires-Dist: pyparsing<3.2,>=2.1.0; extra == "dev"
Requires-Dist: openai>=1.0; extra == "dev"
Provides-Extra: test
Requires-Dist: aiohttp; extra == "test"
Requires-Dist: pytest; extra == "test"
Requires-Dist: black[jupyter]; extra == "test"
Requires-Dist: pre-commit; extra == "test"
Requires-Dist: httpx; extra == "test"
Requires-Dist: psycopg2-binary; extra == "test"
Requires-Dist: requests; extra == "test"
Requires-Dist: pydantic-settings; extra == "test"
Requires-Dist: fastapi; extra == "test"
Requires-Dist: uvicorn[standard]; extra == "test"
Requires-Dist: python-multipart; extra == "test"
Requires-Dist: rdflib<8,>=7.5.0; extra == "test"
Requires-Dist: pyparsing<3.2,>=2.1.0; extra == "test"
Requires-Dist: openai>=1.0; extra == "test"
Provides-Extra: e2e
Requires-Dist: selenium>=4.0; extra == "e2e"
Requires-Dist: webdriver-manager>=4.0; extra == "e2e"
Provides-Extra: viz
Requires-Dist: matplotlib; extra == "viz"
Provides-Extra: brick
Requires-Dist: rdflib<8,>=7.5.0; extra == "brick"
Requires-Dist: pyparsing<3.2,>=2.1.0; extra == "brick"
Provides-Extra: docx
Requires-Dist: python-docx; extra == "docx"
Provides-Extra: platform
Requires-Dist: psycopg2-binary; extra == "platform"
Requires-Dist: requests; extra == "platform"
Requires-Dist: httpx; extra == "platform"
Requires-Dist: pydantic-settings; extra == "platform"
Requires-Dist: fastapi; extra == "platform"
Requires-Dist: uvicorn[standard]; extra == "platform"
Requires-Dist: python-multipart; extra == "platform"
Requires-Dist: openai>=1.0; extra == "platform"
Provides-Extra: bacnet
Requires-Dist: bacpypes3; extra == "bacnet"
Requires-Dist: ifaddr; extra == "bacnet"
Requires-Dist: httpx; extra == "bacnet"
Provides-Extra: monitoring
Requires-Dist: docker; extra == "monitoring"
Dynamic: license-file

# Open-FDD

[![Discord](https://img.shields.io/badge/Discord-Join%20Server-5865F2.svg?logo=discord&logoColor=white)](https://discord.gg/Ta48yQF8fC)
![CI](https://github.com/bbartling/open-fdd/actions/workflows/ci.yml/badge.svg?branch=master)
![MIT License](https://img.shields.io/badge/license-MIT-green.svg)
![Development Status](https://img.shields.io/badge/status-3%20--%20Alpha-orange)
![Python](https://img.shields.io/badge/Python-3.11+-blue?logo=python&logoColor=white)
![BACnet](https://img.shields.io/badge/Protocol-BACnet-003366)
![TimescaleDB](https://img.shields.io/badge/TimescaleDB-compatible-FDB515?logo=timescale&logoColor=black)
![Grafana](https://img.shields.io/badge/Grafana-supported-F46800?logo=grafana&logoColor=white)
[PyPI: open-fdd](https://pypi.org/project/open-fdd/)


<div align="center">

![open-fdd logo](image.png)

</div>

Open-FDD is an open-source knowledge graph fault-detection platform for HVAC systems that helps facilities optimize their energy usage and cost-savings. Because it runs on-prem, facilities never have to worry about a vendor hiking prices, going dark, or walking away with their data. The platform is an AFDD stack designed to run inside the building, behind the firewall, under the owner’s control. It transforms operational data into actionable, cost-saving insights and provides a secure integration layer that any cloud platform can use without vendor lock-in. U.S. Department of Energy research reports median energy savings of roughly 8–9% from FDD programs—meaningful annual savings depending on facility size and energy spend.

The building is modeled in a **unified graph**: Brick (sites, equipment, points), BACnet discovery RDF, platform config, and—as the project evolves—other ontologies such as ASHRAE 223P, in one semantic model queried via SPARQL and serialized to `config/data_model.ttl`.

---


## Quick Start — Open-FDD AFDD Platform Manually by the Human

Open-FDD uses Docker and Docker Compose to orchestrate and manage all platform services within a unified containerized environment. The bootstrap script (`./scripts/bootstrap.sh`) is **Linux only** (tested on Ubuntu Server and Linux Mint, x86; should work on ARM but is untested). Windows is not supported.

### 🚀 Platform Deployment (Docker)

```bash
git clone https://github.com/bbartling/open-fdd.git
cd open-fdd
./scripts/bootstrap.sh
```

This will start the full AFDD edge stack locally: TimescaleDB, API, React UI, BACnet gateway/scraper, weather and FDD loops, and more. **Grafana** and an **MQTT** broker are **optional** (`./scripts/bootstrap.sh --with-grafana`, `--with-mqtt-bridge`); see [Getting Started](docs/getting_started.md). The default protocol is **BACnet** for commercial building automation data. Future releases may add other data sources such as REST/API and Modbus.

Also available is the **partial stack** mode: `./scripts/bootstrap.sh --mode collector`, `--mode model`, or `--mode engine`. See [Modular architecture](docs/modular_architecture.md) for the service matrix and mode behavior.

## Quick Start — OpenClaw (agent)

OpenClaw agents should use the in-repo skill/docs only—start at [`openclaw/SKILL.md`](openclaw/SKILL.md), [`openclaw/README.md`](openclaw/README.md), and [`openclaw/HANDOFF_PROTOCOL.md`](openclaw/HANDOFF_PROTOCOL.md)—defaulting to web-app/testing workflows (plus `./scripts/bootstrap.sh --test`) and using AI data-modeling or virtual-operator modes only when explicitly requested, with HTTP tool discovery at `http://localhost:8000/mcp/manifest` (and optional RAG `http://localhost:8090/manifest`) using Bearer `OFDD_API_KEY` from `stack/.env` (split-machine setup: [OpenClaw integration](docs/openclaw_integration.md#1e-openclaw-on-a-different-machine-than-open-fdd-split-setup)).

### Development: branches and tests

Work off the **`develop`** branch for day-to-day development; open feature branches from `develop` and merge back to `develop`. Releases are cut from `master`. No Docker needed for the test suite. From the repo root:

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytest -v
```

- **`.[dev]`** installs pytest, black, aiohttp, and platform deps so the full suite (open_fdd + HA integration tests) runs.
- **`./scripts/bootstrap.sh --test`** runs frontend checks + pytest + Caddy validate; frontend checks try container-first and fall back to host `npm` when needed. Pytest includes **`test_rdflib_sparql_stack.py`**, which runs the same SPARQL path as `POST /data-model/sparql` so a broken **rdflib + pyparsing** install fails CI before you deploy.
- Test paths are set in `pyproject.toml` (`open_fdd/tests`, `stack/ha_integration/tests`). Run `pytest` with no path to use them.
- Style and workflow: [docs/contributing.md](docs/contributing.md).


> **Note:** If a `develop` branch does not exist, please request one in the `#dev-chat` channel on Discord.


---


## The open-fdd Pyramid


If OpenFDD nails the ontology, the project will be a huge success: an open-source knowledge graph for buildings. Everything else is just a nice add-on.

![Open-FDD system pyramid](https://raw.githubusercontent.com/bbartling/open-fdd/master/OpenFDD_system_pyramid.png)

---

## Online Documentation

- 📖 [**Docs**](https://bbartling.github.io/open-fdd/) — GitHub Pages (Linux quick start, stack, reference).
- 📕 [**Documentation PDF**](https://github.com/bbartling/open-fdd/blob/master/pdf/open-fdd-docs.pdf) — offline / print-friendly bundle.
- ✨ [**LLM prompt (copy/paste template)**](https://bbartling.github.io/open-fdd/modeling/llm_workflow#copy-paste-prompt-template-recommended) — canonical text on the docs site (same section as [**LLM workflow**](https://bbartling.github.io/open-fdd/modeling/llm_workflow)); GitHub Pages serves this path **without** a trailing slash.

---


## Dependencies

[pandas](https://github.com/pandas-dev/pandas) · [PyYAML](https://github.com/yaml/pyyaml) · [FastAPI](https://fastapi.tiangolo.com/)  

Optional: [rdflib](https://github.com/RDFLib/rdflib) (Brick TTL), [matplotlib](https://github.com/matplotlib/matplotlib) (viz)

---

## Contributing

Contributions welcome — Please use the **`develop`** branch for integration. Open pull requests **into `develop`**, not `master`. Branch from `develop` for your work; `master` is reserved for releases and is protected. PR's to the `master` branch will be rejected.

### Syncing your fork with upstream

To bring your fork up to date with the latest `develop` from this repo:

```bash
# Add the upstream repo once (replace with this repo’s URL if you forked from another fork)
git remote add upstream https://github.com/bbartling/open-fdd.git

# Fetch upstream and update your local develop
git fetch upstream
git checkout develop
git merge upstream/develop
git push origin develop
```

Then rebase or merge `develop` into your feature branch as needed. Use `git pull --rebase upstream develop` on your branch if you prefer a linear history.

### Run unit tests before pushing to GitHub

```bash
~/open-fdd$ bash scripts/bootstrap.sh --test
```


---

## License

MIT
