# Selora AI Health Alert: tell the homeowner when their home health score
# is falling, instead of leaving it to be noticed on the Health tab.
#
# The trigger entity is Selora AI's own Home Health sensor,
# ``sensor.selora_ai_home_health`` (0-100, with an ``active_signals``
# attribute carrying the number of open findings). It always exists on a
# home running Selora AI with Health monitoring on, so it is hard-coded in
# the template rather than resolved as a role, because there is nothing for the
# homeowner to pick and no other entity that could fill the slot.
#
# Four automations, all thresholds homeowner-configurable:
#   1. warning:   score sits below ``warn_threshold`` for a sustained
#                  period (default 15 min, matching Selora AI's own
#                  reassessment interval, so a single bad sample can't
#                  page anyone).
#   2. critical:  score falls below ``critical_threshold``, with the
#                  optional spoken announcement.
#   3. drop:      score falls by ``drop_points`` in one reassessment while
#                  still above the warning threshold. This is the
#                  "declining" case: 96 -> 84 is worth knowing about even
#                  though nothing has crossed a threshold yet.
#   4. recovered: score climbs back above ``warn_threshold``. Opt-out via
#                  ``notify_recovery``.
#
# The sensor reads ``unavailable`` when Health monitoring is switched off,
# so every automation guards against unknown/unavailable rather than
# treating a missing score as 0 and alerting on it.
#
# min_integration_version: the Home Health sensor ships with the Health
# tab; older integrations have no such entity and the recipe would install
# an automation that can never fire.
slug: selora-ai-health-alert
version: 1.0.0
title: Selora AI Health Alert
tagline: Get told when your home health score starts sliding, instead of finding out next time you open the Health tab.
description: >-
  Watches Selora AI's own Home Health sensor and notifies you when your
  home's score is declining: a sustained drop below your warning
  threshold, a fall past your critical threshold, or a sharp drop in a
  single reassessment even while the score is still healthy. Each alert
  names the score and how many findings are open. Add one or more
  speakers and critical alerts are announced out loud. Notifies you again
  when the score recovers.
author: Selora AI
released: "2026-08-19"
min_integration_version: "0.13.0"
tags: [maintenance, monitoring, health, alerts]
roles:
  # Announcement speakers: optional. A declining health score is not an
  # emergency, so only the critical alert is spoken; the rest stay on
  # push. min_count 0: leave it empty and the recipe is
  # notification-only. Multi-select so the announcement can fan out.
  - id: announce_speakers
    title: Announcement speakers
    kind: media_player
    min_count: 0
    selection: required
    description: >-
      Optional. Speakers that announce a critical health score out loud
      over text to speech, in addition to the push notification. Leave
      empty to be notified on your phone only.
inputs:
  # Warning threshold. 80 is the example the Health documentation uses for
  # "worth a look" and leaves room above the critical tier. Feeds the
  # numeric_state trigger's ``below``.
  - id: warn_threshold
    type: number
    label: Warning score
    description: >-
      Notify when the home health score falls below this number. 80 leaves
      room for a couple of minor findings without alerting.
    default: 80
  # Critical threshold. Below this the home has real problems (offline
  # devices, failing integrations) rather than a long tail of minor
  # findings, so this tier is the one that can speak on the speakers.
  - id: critical_threshold
    type: number
    label: Critical score
    description: >-
      Notify more urgently, and announce on any speakers you picked, when
      the score falls below this number.
    default: 50
  # How long the score must stay below the warning threshold before the
  # warning fires. Selora AI reassesses every 15 minutes by default, so 15
  # means "still bad on the next reassessment" and a device that drops off
  # for one cycle and comes straight back doesn't notify.
  - id: sustained_minutes
    type: number
    label: Sustained for (minutes)
    description: >-
      How long the score must stay below the warning threshold before you
      are notified. Selora AI reassesses every 15 minutes, so 15 means the
      dip has to survive one more reassessment.
    default: 15
  # Sharp-drop size, in points, for the "declining" alert that fires while
  # the score is still above the warning threshold. 10 is large enough to
  # mean a real finding appeared (a critical finding subtracts its full
  # weight) rather than one more minor item nudging the roll-up.
  - id: drop_points
    type: number
    label: Sharp drop (points)
    description: >-
      Notify when the score falls by at least this many points in a single
      reassessment, even if it is still above the warning threshold. Raise
      it to only hear about large drops.
    default: 10
  # Recovery notification. On by default: an alert with no all-clear
  # leaves the homeowner checking the panel to find out whether whatever
  # they fixed actually moved the score.
  - id: notify_recovery
    type: boolean
    label: Notify when recovered
    description: >-
      Send a follow-up notification when the score climbs back above the
      warning score. Turn off to only hear about problems.
    default: true
  # TTS engine entity for the critical announcement. Auto-resolved by the
  # ``tts_engine`` resolver from the home's configured tts.* entities, so the
  # wizard never shows this field. ``tts.speak`` (not ``tts.cloud_say``,
  # which needs a paid Home Assistant Cloud subscription) so the
  # announcement works on every home. The resolver returns an empty string
  # when the home has no TTS engine; the template then skips the
  # announcement and the recipe stays push-notification-only. The default
  # below is only used by the offline recipe-validation gate, which has no
  # resolver to run; at install the resolver always overwrites it.
  - id: tts_engine
    type: string
    label: Text-to-Speech engine
    description: >-
      Speech engine entity used for the spoken critical announcement.
      Resolved automatically from the Text-to-Speech engines configured in
      Home Assistant.
    resolver: tts_engine
    default: "tts.piper"
package_files:
  - package/automations/health_alert.yaml.j2

{# Selora AI Health Alert: notify when the home health score is falling.

   Everything triggers off Selora AI's own sensor, sensor.selora_ai_home_health
   (0-100, attribute ``active_signals`` = number of open findings). It is
   hard-coded, not a resolved role: the entity id is fixed for every home
   running Selora AI, so there is nothing to bind.

   Thresholds arrive as manifest inputs and are re-declared as automation-level
   ``variables`` so the HA templates can reference them by name instead of
   splicing numbers into a raw block.

   Health monitoring can be switched off, in which case the sensor reads
   ``unavailable``. numeric_state triggers ignore non-numeric states, so the
   threshold automations are safe by construction; the sharp-drop automation
   uses a state trigger and therefore checks both states explicitly.

   Every template stays on a single quoted line so the renderer's trim_blocks
   can't swallow following YAML at an end-of-line tag. #}
automation:
  # 1. Sustained dip below the warning score. ``for`` keeps a single bad
  #    reassessment from paging anyone; the condition hands anything already
  #    past the critical threshold to the critical automation below so one
  #    fall doesn't send two notifications.
  - id: selora_recipe_{{ slug | replace('-', '_') }}_health_warning
    alias: "Selora AI Health Alert: score below warning"
    description: >-
      When the Selora AI home health score stays below the warning score for
      the configured period, send a push notification naming the score and
      how many findings are open.
    mode: single
    variables:
      critical_threshold: {{ inputs.critical_threshold }}
    trigger:
      - platform: numeric_state
        entity_id: sensor.selora_ai_home_health
        below: {{ inputs.warn_threshold }}
        for:
          minutes: {{ inputs.sustained_minutes }}
    condition:
      # is_number guard: Health monitoring can be switched off in the window
      # between the dip starting and this firing, which leaves the sensor
      # unavailable. Without the guard the notification would read
      # "unavailable out of 100".
      - condition: template
        value_template: "{% raw %}{{ states('sensor.selora_ai_home_health') | is_number and (states('sensor.selora_ai_home_health') | float) >= critical_threshold }}{% endraw %}"
    action:
      - variables:
          score: "{% raw %}{{ states('sensor.selora_ai_home_health') }}{% endraw %}"
          signals: "{% raw %}{{ state_attr('sensor.selora_ai_home_health', 'active_signals') | default(0, true) }}{% endraw %}"
      - service: notify.notify
        data:
          title: "Home health declining"
          message: "{% raw %}Home health is {{ score }} out of 100 with {{ signals }} open finding(s). Open the Selora AI Health tab to see what needs attention.{% endraw %}"

  # 2. Below the critical score. Same sensor, no ``for``: at this point the
  #    home has real problems (offline devices, failing integrations) and the
  #    delay only postpones the fix. This is the tier that speaks aloud.
  - id: selora_recipe_{{ slug | replace('-', '_') }}_health_critical
    alias: "Selora AI Health Alert: score critical"
    description: >-
      When the Selora AI home health score falls below the critical score,
      send an urgent push notification and, if speakers are configured,
      announce it out loud.
    mode: single
    trigger:
      - platform: numeric_state
        entity_id: sensor.selora_ai_home_health
        below: {{ inputs.critical_threshold }}
    action:
      - variables:
          score: "{% raw %}{{ trigger.to_state.state }}{% endraw %}"
          signals: "{% raw %}{{ state_attr('sensor.selora_ai_home_health', 'active_signals') | default(0, true) }}{% endraw %}"
      - service: notify.notify
        data:
          title: "Home health critical"
          message: "{% raw %}Home health has dropped to {{ score }} out of 100 with {{ signals }} open finding(s). Check the Selora AI Health tab now.{% endraw %}"
{% if roles.announce_speakers and inputs.tts_engine %}
      # Spoken announcement on the configured speakers, via the auto-resolved
      # TTS engine. tts.speak works without a Home Assistant Cloud
      # subscription; the speakers go in media_player_entity_id.
      - service: tts.speak
        target:
          entity_id: {{ inputs.tts_engine }}
        data:
          media_player_entity_id:
{% for player in roles.announce_speakers %}
            - {{ player }}
{% endfor %}
          message: "{% raw %}Attention. Home health has dropped to {{ score }} out of 100. Check the Selora AI Health tab.{% endraw %}"
{% endif %}

  # 3. Sharp drop while the score is still healthy, the "declining" case a
  #    threshold can't catch. 96 -> 84 means a finding with real weight just
  #    appeared, and waiting for it to cross the warning score wastes the head
  #    start. The condition requires the new score to still be at or above the
  #    warning threshold so a drop that lands in warning territory is reported
  #    once, by automation 1.
  - id: selora_recipe_{{ slug | replace('-', '_') }}_health_drop
    alias: "Selora AI Health Alert: sharp drop"
    description: >-
      When the Selora AI home health score falls by the configured number of
      points in a single reassessment while still above the warning score,
      send a heads-up naming the drop.
    mode: single
    variables:
      drop_points: {{ inputs.drop_points }}
      warn_threshold: {{ inputs.warn_threshold }}
    trigger:
      - platform: state
        entity_id: sensor.selora_ai_home_health
    condition:
      # Both states must be real numbers: a reload or a Health-monitoring
      # toggle produces unknown/unavailable, and float(0) on those would read
      # as a 100-point crash.
      - condition: template
        value_template: "{% raw %}{{ trigger.from_state is not none and trigger.to_state is not none and trigger.from_state.state not in ['unknown', 'unavailable', 'none'] and trigger.to_state.state not in ['unknown', 'unavailable', 'none'] }}{% endraw %}"
      - condition: template
        value_template: "{% raw %}{{ (trigger.from_state.state | float) - (trigger.to_state.state | float) >= drop_points and (trigger.to_state.state | float) >= warn_threshold }}{% endraw %}"
    action:
      - variables:
          signals: "{% raw %}{{ state_attr('sensor.selora_ai_home_health', 'active_signals') | default(0, true) }}{% endraw %}"
      - service: notify.notify
        data:
          title: "Home health dropping"
          message: "{% raw %}Home health fell from {{ trigger.from_state.state }} to {{ trigger.to_state.state }} out of 100, with {{ signals }} open finding(s). Still healthy, but something just changed.{% endraw %}"
{% if inputs.notify_recovery %}

  # 4. All-clear. Without it the homeowner has to open the panel to find out
  #    whether the thing they fixed actually moved the score.
  - id: selora_recipe_{{ slug | replace('-', '_') }}_health_recovered
    alias: "Selora AI Health Alert: score recovered"
    description: >-
      When the Selora AI home health score climbs back above the warning
      score, send an all-clear notification.
    mode: single
    trigger:
      - platform: numeric_state
        entity_id: sensor.selora_ai_home_health
        above: {{ inputs.warn_threshold }}
    action:
      - variables:
          score: "{% raw %}{{ trigger.to_state.state }}{% endraw %}"
      - service: notify.notify
        data:
          title: "Home health recovered"
          message: "{% raw %}Home health is back up to {{ score }} out of 100.{% endraw %}"
{% endif %}