Health Tree
Health Tree is a Python library for health across a dependency graph. You describe what depends on what and feed it check results. It works out which failure is the cause and which are symptoms, what the failure takes down and how much that matters, and who should hear about it, how loudly and when.
It's pure Python with no runtime dependencies and no Home Assistant code, and it does no I/O. It never reads a clock, opens a connection or sends a message; your code does those things. That keeps it usable for anything you can draw as a dependency graph.
Using Home Assistant? Install Homeostatic, the integration built on Health Tree. It discovers your integrations and devices, feeds them to the library and sends the notifications.
The problem
When a Zigbee coordinator drops at 2 a.m., every device behind it goes unavailable too. A monitor that watches each one raises forty alerts, all about symptoms, and none of them says what actually stopped working or whether it's worth waking someone for. The same night, a motion sensor's battery runs low, which can wait for the morning. The same shape turns up anywhere there are dependencies: a database behind three services, or a router behind twenty hosts.
Handling this well takes two decisions. The first is what counts as one problem: the coordinator failed, and the devices failed because of it. The second is who to tell, and when. Hall motion lighting is out, and that's worth a page at 2 a.m. The battery isn't.
How Health Tree handles it
You register nodes, things that either work or don't, such as the coordinator, a light or an integration's login, and the edges between them that say which nodes need which. A function, such as motion lighting, is a node too. It depends on the devices it needs and carries an importance from low to critical.
Your code reports check results as observations. The engine turns them into episodes: one per root cause, with the symptoms recorded on it, updated in place and resolved once. An episode is as important as the most important thing its root takes down, so the coordinator's episode is high because motion lighting is.
The attention policy turns episodes into deliveries using rules you configure. A high-importance outage goes out at once, through quiet hours. A low battery waits for the morning digest. Quiet hours, digests, reminders and escalation are configuration. Acknowledgment and shelving are calls your code makes when a person asks.
Health Tree never sends anything itself. Your code, called the adapter, discovers what to watch, reports observations, keeps time and delivers the messages. Concepts explains each of these in detail.
Example
The coordinator from above, with two devices behind it and the function that needs them both:
from datetime import UTC, datetime, time, timedelta
from zoneinfo import ZoneInfo
from health_tree.engine import Engine
from health_tree.policy import Policy
from health_tree.types import (
Check,
Edge,
EngineSettings,
Importance,
Loudness,
Match,
Node,
Observation,
PolicyConfig,
PolicyContext,
QuietHours,
Recipient,
Rule,
Status,
)
link = Check(
check_id="link",
raise_hold=timedelta(0),
clear_hold=timedelta(minutes=2),
ttl=timedelta(hours=1),
unknown_hold=timedelta(minutes=15),
)
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
engine.register_many(
[
Node(node_id="coordinator", checks=(link,)),
Node(
node_id="hall_motion", depends_on=(Edge(to="coordinator"),), checks=(link,)
),
Node(
node_id="hall_light", depends_on=(Edge(to="coordinator"),), checks=(link,)
),
Node(
node_id="motion_lighting",
kind="function",
importance=Importance.HIGH,
depends_on=(Edge(to="hall_motion"), Edge(to="hall_light")),
),
],
now,
)
def report(status: Status, reason: str) -> list[Observation]:
return [
Observation(
node_id=n, check_id="link", status=status, reason=reason, observed_at=now
)
for n in ("coordinator", "hall_motion", "hall_light")
]
engine.ingest_many(report(Status.PASS, "ok"), now)
now += timedelta(minutes=1) # the coordinator drops, and both devices with it
events = engine.ingest_many(report(Status.FAIL, "unavailable"), now)
for event in events:
print(
type(event).__name__,
event.episode.anchor,
event.episode.importance.value,
sorted(event.episode.recorded),
)
owner = Recipient(
channels=("phone",), quiet_hours=QuietHours(start=time(22, 30), end=time(7, 0))
)
policy = Policy(
PolicyConfig(
batch=timedelta(seconds=30),
timezone=ZoneInfo("America/Chicago"),
recipients={"owner": owner},
digests={},
rules=(
Rule(
match=Match(
importance=frozenset({Importance.HIGH, Importance.CRITICAL})
),
loudness=Loudness.URGENT,
to=("owner",),
),
Rule(match=Match(), loudness=Loudness.NOTIFY, to=("owner",)),
),
)
)
for event in events:
for delivery in policy.handle(event, now, PolicyContext()):
print(delivery.recipient, delivery.loudness.value, delivery.channels)
EpisodeOpened coordinator high ['hall_light', 'hall_motion']
owner urgent ('phone',)
Three nodes failed and one episode opened, anchored on the coordinator: the anchor is the root cause. The two devices are recorded on it as symptoms. Their own status is still fail, because that's what their checks saw. The episode is high because motion lighting depends on what failed.
It's 02:41 and the owner's quiet hours run until 07:00. Rules are checked in order and the first match wins, so a high-importance episode is urgent. Urgent deliveries skip the batch delay and quiet hours, so it goes out now. If motion lighting were normal, the second rule would match, handle would return nothing, and the notification would come out of policy.advance at 07:00.
The check's holds and the engine settings control timing: how long a failure must last before it counts, how long a recovery must last before it clears, and how failures that arrive together are grouped. Time explains each one.
A delivery names the episode, the recipient and the recipient's channel ids. Turning it into a push notification, a spoken announcement or a flashing light is up to your code.
How it fits into your code
Neither the engine nor the policy reads a clock. Every call takes now, and next_deadline() tells you when to call advance next, so your code needs one timer. Both save their whole state to JSON-compatible data with snapshot() and pick up again after a restart with restore(), with every episode, hold and reminder intact. The library makes the same decisions from the same inputs, so behavior can be written down as fixtures and replayed in tests.
The library reasons about what you tell it. It doesn't discover devices, decide when a condition such as a door left open holds, or deliver anything. It also can't report that its own process has died, so a deployment needs a watchdog outside it. Using Health Tree shows how an adapter does its share.
Install
pip install health-tree
Health Tree needs Python 3.14 or newer. It's alpha software, and the API may change before 1.0.
Documentation
- Concepts: nodes, checks, episodes, importance and the attention policy.
- Using Health Tree: how-tos for adapter authors, with runnable examples.
- RFP: the design document, with every rule the engine and policy follow.
- Architecture decisions: why it works the way it does.
- Fixtures: stories and scenarios in YAML, which the test suite runs as the executable spec.
- Changelog: what changed in each release.
- Contributing: setup, checks and releases.
- Security: how to report a vulnerability.
License
Metadata
Release files for health-tree 0.9.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| health_tree-0.9.0.tar.gz | 250.0 kB | With provenance | Details for health_tree-0.9.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| health_tree-0.9.0-py3-none-any.whl | Python 3 | none | any | Details for health_tree-0.9.0-py3-none-any.whl |
Total release size: 290.0 kB
Release files / health_tree-0.9.0.tar.gz
| Download URL | health_tree-0.9.0.tar.gz |
|---|---|
| Size | 250.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
0b64ef96d772c42272f40c90cd788cd47d1e163b64f15ec81b8768fd2a3e12a0
|
|
BLAKE2b-256 checksum How to use checksums |
a95ce154ca2a43c265c24d6c3664f5f8306e5b33fc4e047441f24bf52c76d241
|
| 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 Oct 18, 2026.
Transparency logRelease files / health_tree-0.9.0-py3-none-any.whl
| Download URL | health_tree-0.9.0-py3-none-any.whl |
|---|---|
| Size | 40.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
640b3a04f2d3bf6e5105f8c21075c349597272331bf656efbe623b0c9d70eac0
|
|
BLAKE2b-256 checksum How to use checksums |
fb09adeca1e70bcf624235b7729000e80a2e0241f4fe8697224414161ad77803
|
| 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 Oct 18, 2026.
Transparency logSecurity for health-tree 0.9.0
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.
Attestation for health_tree-0.9.0.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 Oct 18, 2026.
Transparency logA 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.