Skip to main content

Health Tree

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

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

MIT

Metadata

Release files for health-tree 0.6.0

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.6.0
File Size Uploaded Provenance Actions
health_tree-0.6.0.tar.gz 227.7 kB With provenance Details for health_tree-0.6.0.tar.gz

Built distribution (wheel)

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

Total release size: 262.9 kB

Release files / health_tree-0.6.0.tar.gz

Download URL health_tree-0.6.0.tar.gz
Size 227.7 kB
Tags Source
SHA-256 checksum
How to use checksums
3cff902eecb82806561f10de3738cfe36a3158a9c343e168c6716fe3a79efab8
BLAKE2b-256 checksum
How to use checksums
53e7c389d9b63ccccda9573aa4bc5a9a5b7b8b9cc5db9c42d0b2a29c61d614b8
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 13, 2026.

Transparency log

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

Download URL health_tree-0.6.0-py3-none-any.whl
Size 35.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
f1bbb43f06a0f34fc54f18c673619de3184f07e3c0c33b0c6d5f8c4f087bcdfe
BLAKE2b-256 checksum
How to use checksums
3ef5d599fb7c33a89548167bdbbdeff7d427e90279186ed0045bee5f850cf9bc
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 13, 2026.

Transparency log

Security for health-tree 0.6.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.

Select from 2 files

Attestation for health_tree-0.6.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 13, 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