PoolOS

A vendor-independent automation platform for intelligent swimming pool and spa control.

PoolOS is a deterministic automation platform that separates automation policy from hardware. Applications define what should happen, while PoolOS determines how to evaluate, authorize, deliver, verify, explain, record, and publish those actions through vendor-specific boundaries.

PoolOS is a vendor-independent pool and spa control platform with both observation/intelligence and physically commissioned control domains. Live control is intentionally scoped rather than governed by one global actuation switch: manual control, automatic filtration, automatic thermal execution, sanitation, and grid-outage safety retain independent authority and safety gates.

Its runtime model is:

OBSERVE -> EVALUATE -> DECIDE -> AUTHORIZE -> DELIVER -> VERIFY
                              |
                              +-> EXPLAIN / RECORD / PUBLISH

A domain may deliver a physical command only when its own authority, ownership, evidence, transport, safety, and verification requirements are satisfied. Read-only advisory subsystems remain non-authoritative by design.

Features

• Vendor-independent architecture
• Canonical typed observation framework
• Durable transition/checkpoint observation history for behavioral analysis
• Behavioral inference with explicit confidence and raw-evidence provenance
• Daily actual-operation retrospectives with evidence-bounded counterfactual comparison
• High-fidelity event-driven Home Assistant observation with periodic reconciliation
• Deterministic decision and planning layers
• Runtime-mode safety boundary
• Simulation-first development
• Decision explanations and flight recording
• Restart recovery and deterministic replay
• Home Assistant observation and publication boundaries
• Comprehensive automated testing
• GitHub Actions continuous integration

Architecture

Home Assistant and vendor observations
                 |
                 v
              PoolOS
                 |
      observe / evaluate / decide
       explain / record / publish
                 |
                 v
     Scoped command-delivery boundaries
   (domain authority + safety + verification)

Repository Structure

poolos/                     Installable vendor-independent PoolOS package
intellicenter/              Pentair IntelliCenter Home Assistant integration source
intellicenter/api/          Immutable internal IntelliCenter read-model package
tests/                      PoolOS and IntelliCenter read-model tests
docs/                       Architecture, development, roadmap, and ADRs
config/                     Example installation configuration

The repository root and the nested poolos/ Python package intentionally share the same name. They are not accidental duplicates.

The root intellicenter/ directory contains the retained IntelliCenter protocol/read-model source used by PoolOS development and contract testing. The production PoolOS Home Assistant integration ships under custom_components/poolos/ and uses the pinned pyintellicenter dependency for its native controller transport.

Development

Clone the repository:

git clone https://github.com/davidabuch/poolos.git
cd poolos

Create a virtual environment:

python3.13 -m venv .venv
source .venv/bin/activate

Install dependencies:

python -m pip install --upgrade pip
python -m pip install -e ".[dev]"

Validate the project:

python -m compileall poolos intellicenter
python -m ruff check poolos intellicenter tests
python -m mypy poolos
python -m pytest

MyPy currently checks the installable poolos package. Home Assistant adapter code and the IntelliCenter read-model boundary are additionally protected by compilation, Ruff, structural, contract, and runtime-focused tests.

Current Status

Component	Status
Runtime and event model	Complete
Typed observations	Complete
Decision intelligence	Complete
Planning and policy	Complete
Explanations and flight recorder	Complete
Restart recovery and replay	Complete
Runtime diagnostics and golden scenarios	Complete
Home Assistant observation/publication	Complete
Persistent observation/event history	Complete
Behavioral inference and daily retrospective	Complete
High-fidelity event-driven HA observation	Complete
IntelliCenter immutable/native read model	Complete for current production scope
Home Assistant PoolOS deployment	Live / HACS-managed
Manual equipment control	Live
Automatic filtration	Live behind its dedicated gate
Automatic thermal execution	Live behind dedicated automatic + thermal-live gates
Grid-outage physical safety	Live behind its dedicated gate
Sanitation sessions	Live / operator initiated
Vendor-neutral RPM/GPM capability model	Complete for current production scope
1.0 release-readiness reconciliation	Complete

Roadmap

The current roadmap is maintained in docs/ROADMAP.md.

Live control must retain explicit scoped command-delivery, ownership, safety, validation, verification, and audit boundaries.

Philosophy

PoolOS treats pool automation as an operating-system problem rather than a controller problem. By separating observations, policy, planning, explanation, runtime state, and command delivery, automation logic becomes portable, testable, and independent of any specific manufacturer.

Contributing

Before submitting changes, ensure the repository passes all required validation checks:

python -m compileall poolos intellicenter
python -m ruff check poolos intellicenter tests
python -m mypy poolos
python -m pytest

Review git diff and confirm GitHub Actions is green before merging or deploying.

License

PoolOS is currently marked proprietary while private development continues. No public-use license has been granted yet. Licensing must be selected and documented before the repository is made public or distributed through HACS.