Skip to main content

Health Tree

When the Zigbee coordinator drops at 2 a.m., forty entities go unavailable. Health Tree turns that into one alert, about the coordinator, that says the hall motion lighting is what you just lost and knows that is worth waking you for. When a battery dies, you read about it over coffee.

PyPI Downloads Python CI Security codecov Dependencies Typed: mypy strict Ruff License: MIT

Health Tree is the health engine under Homeostatic, a Home Assistant integration. You describe what depends on what in your house and feed it observations. It tells a root failure from its symptoms, works out what the failure takes down and how much that matters, and decides who should hear about it, how loudly, and when.

It is pure Python with no Home Assistant code and no dependencies, so it also works for anything else you can draw as a dependency graph.

Want this in your house? Install Homeostatic. It discovers your integrations, devices, and automations, feeds them to Health Tree, and delivers the notifications. This repository is the reasoning underneath it.

The problem

Home Assistant has the inventory of your house: host, add-ons, integrations, devices, automations, and the machines they depend on. What it lacks is a health layer. When the Frigate host goes down, it sees the Frigate integration fail, the cameras go unavailable, and the person sensors go unavailable. It does not see that those are one problem, or that motion lighting in four rooms just stopped working because of it. You find out when you walk into a dark hallway.

The quiet failures are worse. A motion sensor's battery dies and it simply stops talking; nothing turns red. The Spotify login expires at 3 a.m. and nobody notices until there are guests in the backyard. Frigate's host is up, so every availability check passes, but the detector hung and every person sensor has been reading "clear" ever since. The garage door was told to close and is still open. The AI box has had updates pending for ten months.

Failures come in five shapes, and each needs a different kind of check to catch it:

Shape Example Check that catches it
Loud An integration fails to load State
Quiet A sensor stops reporting Freshness: ttl, then stale
Plausible but wrong A person sensor reads "clear" because the detector hung Liveness of the signal path
Latent A login expired and nobody notices until the music is wanted State, evaluated when it breaks
Gradual A disk fills; a battery drains Capacity, with a projected deadline

Two more kinds of trouble are not component failures at all: an operation that did not do what it was told (the garage door), and maintenance debt with no symptom (the updates). And a third is not a failure: a situation you asked to hear about while the house is working fine, like the front door left open overnight.

Monitoring today gives you two options. Watch every entity and drown, or watch nothing.

What Health Tree does instead

You give it a graph of hard dependencies: the hall light and motion sensor depend on the Zigbee coordinator; the coordinator depends on the host; the function "motion lighting" depends on the light and the sensor. Functions are nodes like anything else, and they are where you say what matters: motion lighting is high, backyard music is normal.

Then three things happen that Home Assistant cannot do on its own.

One cause, one episode. When the coordinator fails and the devices behind it fail with it, one episode opens on the coordinator. The devices are recorded on it as symptoms, not paged separately. When an Insteon controller chokes and thirty devices report command_failed within a minute, that is one episode, not thirty-one. As devices recover they leave it, and if two are still broken after the rest come back, each gets its own episode: those two are broken on their own. If the root turns up late, its episode absorbs the ones already open on its symptoms. When it is over, it recovers once.

Importance flows up. The coordinator is just a box. But motion lighting depends on it and motion lighting is high, so the episode is high. An episode is as important as the most important thing its root takes down, which is what lets a policy say "wake me for this" without anyone rating every device by hand.

Attention is policy, not status. Rules decide who hears what, how loudly, and when. A high-importance outage is urgent and goes through quiet hours. A low battery goes to the 8 a.m. digest. Pending updates sit in the digest, get a weekly reminder, and rise a level after thirty days. Quiet hours, digests, reminders, escalation, acknowledgment, and shelving are configuration, not code.

Because every episode carries its cause, its reasons, its impact, and a loudness, an integration like Homeostatic can say things like:

02:40 · Motion lighting is off in four rooms because the Frigate host is unreachable.

08:00 digest · The basement motion sensor went quiet at 03:58. Battery likely dead.

07:00 · Spotify needs a new login. Backyard music is blocked until it has one. (Opened at 03:10, held until quiet hours ended.)

Health Tree also answers questions. What is true of this node, from its own checks (explain)? What broke first, and what does it take down (episodes, impact)? Is this set of functions ready right now, and if not, what is blocking it (readiness)? How does this room or this integration look as a whole (rollup)? And what in the house has no checks at all (coverage)?

A story the test suite runs

Behavior is specified as stories drawn from real failures in one house, and the test suite runs them. Home Assistant users will find the format familiar. This is story 8, abridged:

policy:
  recipients:
    michael: {channels: [phone], quiet_hours: "22:30-07:00"}
  digests:
    morning: {at: "08:00", to: michael}
  rules:
    - match: {category: operation, importance: [high, critical]}
      loudness: urgent
      to: michael
    - match: {category: maintenance}
      loudness: digest
      digest: morning
    - match: {status: fail}
      loudness: notify
      to: michael
    - match: {}
      loudness: digest
      digest: morning

graph:
  - id: hub
    kind: device
    checks: [{id: link, ttl: 1h, ...}]
  - id: garage_door
    kind: device
    depends_on: [hub]
    checks: [{id: command, labels: {category: operation}, ...}]
  - id: garage
    kind: function
    importance: high
    depends_on: [garage_door]

steps:
  - at: 2026-09-24T23:10:30Z
    ingest:
      - {node: garage_door, check: command, status: fail, reason: command_failed,
         message: Told to close at 23:10 and still open}
    expect:
      events:
        - {opened: {anchor: garage_door, importance: high, reasons: [command_failed]}}
      deliveries:
        - {loudness: urgent, to: michael}
  - at: 2026-09-24T23:11:00Z
    ingest:
      - {node: garage_door, check: command, status: pass, reason: command_completed}
  - at: 2026-09-24T23:11:31Z
    expect:
      events:
        - {resolved: {resolution: cleared}}

The door is only a device, but the garage function behind it is high, so the episode is high. The first rule matches a high-importance operation and makes it urgent, so it reaches Michael's phone at 23:10:30, through quiet hours. When the door reports the command completed and the 30-second clear hold passes, the episode resolves once. Had this been a battery_low warning on the door's hub instead, it would have fallen through to the last rule and waited for the morning digest, and nobody's sleep would have been touched.

There are eleven stories like this one and more than sixty finer-grained scenarios under tests/fixtures. Together they are the executable spec.

Using the library

The engine takes a graph and observations and returns events. Here the same Zigbee outage as above, in Python:

from datetime import UTC, datetime, timedelta

from health_tree.engine import Engine
from health_tree.types import Check, Edge, EngineSettings, Importance, Node, Observation, Status

# One way a device can fail: its link drops. The holds keep flaps out of the alerts.
LINK = Check(
    check_id="link",
    raise_hold=timedelta(0),
    clear_hold=timedelta(minutes=2),
    ttl=timedelta(hours=1),
    unknown_hold=timedelta(minutes=5),
)


def device(node_id: str) -> Node:
    return Node(node_id=node_id, kind="device", depends_on=(Edge(to="zigbee"),), checks=(LINK,))


engine = Engine(
    EngineSettings(
        settle=timedelta(seconds=30),
        rejoin_grace=timedelta(minutes=2),
        startup_grace=timedelta(0),
        coalesce_count=3,
        coalesce_window=timedelta(minutes=1),
    )
)
now = datetime(2026, 9, 29, 7, 40, tzinfo=UTC)  # 02:40 in Chicago

# Two devices behind a Zigbee coordinator, serving one function you care about.
engine.register_many(
    [
        Node(node_id="zigbee", kind="integration", checks=(LINK,)),
        device("hall_motion"),
        device("hall_light"),
        Node(
            node_id="motion_lighting",
            kind="function",
            importance=Importance.HIGH,
            depends_on=(Edge(to="hall_motion"), Edge(to="hall_light")),
        ),
    ],
    now,
)


def observe(status: Status, reason: str) -> list[Observation]:
    return [
        Observation(node_id=n, check_id="link", status=status, reason=reason, observed_at=now)
        for n in ("zigbee", "hall_motion", "hall_light")
    ]


engine.ingest_many(observe(Status.PASS, "ok"), now)

# The coordinator drops, and both devices go unavailable with it.
now += timedelta(minutes=1)
events = engine.ingest_many(observe(Status.FAIL, "unavailable"), now)
events += engine.advance(now + timedelta(seconds=30))

for event in events:
    episode = event.episode
    print(type(event).__name__, episode.anchor, episode.importance.value)
    print("  recorded:", sorted(episode.recorded))
    print("  impact:  ", sorted(episode.impact))
# EpisodeOpened zigbee high
#   recorded: ['hall_light', 'hall_motion']
#   impact:   ['hall_light', 'hall_motion', 'motion_lighting']

print(engine.readiness(["motion_lighting"]).answer)
# blocked

Three nodes failed and one episode opened, on the coordinator. The two devices are recorded on it, and the episode took the high importance of the function it broke. Nothing about the devices' own status was rewritten: each still reports exactly what its own check saw.

The attention policy turns those events into deliveries:

from datetime import time
from zoneinfo import ZoneInfo

from health_tree.policy import Policy
from health_tree.types import (
    Loudness,
    Match,
    PolicyConfig,
    PolicyContext,
    QuietHours,
    Recipient,
    Rule,
)

policy = Policy(
    PolicyConfig(
        batch=timedelta(0),
        timezone=ZoneInfo("America/Chicago"),
        recipients={
            "michael": Recipient(
                channels=("phone",),
                quiet_hours=QuietHours(start=time(22, 30), end=time(7, 0)),
            )
        },
        digests={},
        rules=(
            # High or critical importance is urgent and goes through quiet hours.
            Rule(
                match=Match(importance=frozenset({Importance.HIGH, Importance.CRITICAL})),
                loudness=Loudness.URGENT,
                to=("michael",),
            ),
            # Everything else waits for quiet hours to end.
            Rule(match=Match(), loudness=Loudness.NOTIFY, to=("michael",)),
        ),
    )
)

for event in events:
    for d in policy.handle(event, now, PolicyContext()):
        print(type(d).__name__, d.recipient, d.loudness.value, d.channels)
# Notification michael urgent ('phone',)

It is 02:40 and Michael's quiet hours run until 07:00, but the episode is high, so the first rule makes it urgent and it goes out now. Make motion_lighting normal instead and handle returns nothing at 02:40; the same notification comes out of policy.advance at 07:00.

A delivery names the episode, the recipient, the loudness, and the recipient's channel ids. It never says how to reach someone. The integration turns a delivery into a push notification, a spoken announcement, a light, or a phone call, and renders the message from the episode's cause, reasons, and impact.

The engine and the policy never read a clock and never do I/O. Every call takes now, and time only moves when you pass a later one. That is what makes the stories above runnable as tests, and it is why the whole state can be snapshotted to JSON and restored after a restart with every episode, hold, and reminder intact. docs/usage.md covers registration, acknowledgment, shelving, digests, and restart.

Principles

  • A node reports only what its own checks saw. A failed dependency never rewrites a node's status. A muted node is muted because a known cause explains it, not because of where it sits in a tree.
  • Cause flows down. A failed node mutes notifications for the dependents that fail with it.
  • Importance flows up. An episode is as important as the most important thing its root takes down.
  • One root, one episode. Updated in place, absorbs roots that turn up late, coalesces siblings that fail together, and recovers once.
  • A node is one capability. If a check's failure would not stop every dependent, it belongs on another node. Frigate detection and Frigate recording are two nodes, so a full recording disk does not take down motion lighting. Maintenance debt gets its own node that nothing depends on, so it never mutes anything.
  • Attention is policy, not status. Rules decide who hears what, how loudly, and when. Nothing about a node's health changes because someone was or was not told.
  • Delivery is the integration's job. The library decides; the integration acts.

The model is four separate jobs, not one hierarchy, because a single device sits in an area, belongs to an integration, routes through a controller, runs on a battery, and serves a function:

Job Question Shape Mutes?
Cause What broke what? One graph of hard dependencies Yes, and it is the only thing that may
Views How do I read the house? Named groupings, as many as needed Never
Problem definitions What can go wrong with this thing? Checks the integration attaches to each node No
Attention What interrupts whom, how, and when? Policy rules Decides delivery, never status

How it is built

  • Pure and deterministic. Python 3.14, no runtime dependencies, no Home Assistant imports, no I/O, threads, event loop, sleeping, or clock reads. Ruff's banned-API list keeps the clock, threads, asyncio, and Home Assistant out of src/. The same inputs always produce the same events.
  • Specified before it was written. The design of record is an RFP that states every rule the engine follows. The public records and the fixture runner were written first; the engine was written to make the fixtures pass.
  • The spec is executable. Eleven stories and more than sixty scenarios live as YAML fixtures under tests/fixtures, run by one runner. Every behavior change ships with a fixture. The stories are the ones told above: the Frigate host, the hung detector, the expired login, the dead battery, the filling disk, the AI box, the Eero node, the garage door, the choking Insteon controller, the front door open overnight, the dishwasher out of rinse aid.
  • Tested past the fixtures. 376 tests with more than 98 percent branch coverage, and Hypothesis properties over random graphs and timelines for the invariants: one root episode per anchor, a muted node never opens an episode, nothing opens inside a quiet window, everything resolves once every check passes, a restored snapshot behaves exactly like the engine it replaced, and batch order does not matter.
  • Every decision is written down. Three dozen architecture decision records cover the choices that would be easy to reverse by mistake, from "status is observed, never rewritten" to "a situation is an edgeless node". An accepted ADR is never edited; it is superseded.
  • Strictly typed. mypy in strict mode, and the ruff rule set Home Assistant core uses, so the code reads like the platform it serves.
  • Running. Homeostatic runs on it in a real house.

Modules

Part Module Owns
Engine health_tree.engine Graph, checks, evaluation, inhibition, episodes, importance, quiet windows, snapshots, queries
Attention policy health_tree.policy Rules, recipients, loudness, quiet hours, digests, reminders, escalation, acknowledgment, shelving, scheduled reports
Records health_tree.types The frozen records the engine and policy take and return

Two things are deliberately not here. The library cannot report the death of the process it runs in, so any deployment needs an external watchdog. And it never decides that a situation holds: your own Home Assistant rule decides the front door has been open too long, and reports it.

Install

pip install health-tree

Requires Python 3.14. The package is pure Python with no dependencies.

Project status

0.5, alpha. The engine and the attention policy pass every story and scenario fixture, and Homeostatic runs on it in a real-house pilot. The design of record is docs/rfp.md. Synthetic scenarios establish the library's behavior; proofs against real device observations belong to adapters and remain outstanding. The API may still change before 1.0.

Documentation

Development

You need uv and git. uv installs Python 3.14 itself.

git clone https://github.com/mjcumming/health-tree.git
cd health-tree
uv sync
uv run prek install
make check        # everything CI runs: hooks, tests with coverage, build

make help lists the other targets. On Windows, the make targets need Git Bash or WSL, and each one is a short uv run command you can run directly.

src/health_tree/     package: engine, policy, and types
tests/               unit and property tests, and the fixture runner
tests/fixtures/      stories and scenarios: the executable spec
docs/rfp.md          design of record
docs/adr/            architecture decision records

License

MIT

Metadata

Release files for health-tree 0.5.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for health-tree 0.5.1
File Size Uploaded Provenance Actions
health_tree-0.5.1.tar.gz 208.4 kB With provenance Details for health_tree-0.5.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for health-tree 0.5.1
File Interpreter ABI Platform Actions
health_tree-0.5.1-py3-none-any.whl Python 3 none any Details for health_tree-0.5.1-py3-none-any.whl

Total release size: 245.9 kB

Release files / health_tree-0.5.1.tar.gz

Download URL health_tree-0.5.1.tar.gz
Size 208.4 kB
Tags Source
SHA-256 checksum
How to use checksums
2e43e75af567dd14a36c9ac4c5a6c15791c1094e974a47c3dac96533658f7fd5
BLAKE2b-256 checksum
How to use checksums
c24aff7b14824fca4a9e7853b7a3378288d5a514af07487404b0d9fbffa324ca
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 30, 2026.

Transparency log

Release files / health_tree-0.5.1-py3-none-any.whl

Download URL health_tree-0.5.1-py3-none-any.whl
Size 37.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
eafcb12a70feed0328484d84501f4f1b0ac40c468d4f919d328635e1b0875787
BLAKE2b-256 checksum
How to use checksums
d5d67ccd8aecc028448ff952ef62cd5fca1c6eee71e029624149dce94787863c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 30, 2026.

Transparency log

Security for health-tree 0.5.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for health_tree-0.5.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 30, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page