SOFI Ticker Saturation Tint Implementation Plan¶

pytest==9.1.1
PyYAML==6.0.3
yamllint==1.38.0
Jinja2==3.1.6

"""SOFI Ticker resting tint (§41) — move magnitude is encoded in SATURATION.

Spec: docs/superpowers/specs/2026-07-24-sofi-ticker-saturation-tint-design.md

Brightness is constant (55%) so it carries no information; saturation ramps
40→100 across 0→±4%; hue stays binary for direction.

These tests RENDER the script's `variables:` block with Jinja2 the way HA does
(sequential binding, native-typed results) rather than string-matching the YAML.
check_config validates SCHEMA, not template EXECUTION — bad math ships past CI.
"""
import ast
import json

import jinja2

BULB = "light.louis_office_sengled_a19_bulb_2"


def _native(text):
    """Mimic HA's native-typed template result (parse_result=True).

    Load-bearing: if `flat` came back as the STRING 'False' it would be truthy
    and every single day would render amber.
    """
    t = text.strip()
    try:
        return ast.literal_eval(t)
    except (ValueError, SyntaxError):
        return t


def _market_branch(scripts):
    """The `choose` branch that runs during market hours."""
    return scripts["sofi_ticker_render"]["sequence"][0]["choose"][0]


def _vars_block(scripts):
    for step in _market_branch(scripts)["sequence"]:
        if "variables" in step:
            return step["variables"]
    raise AssertionError("market-hours branch must define a variables block")


def _verify_template(scripts):
    """The retry loop's 'did the command land?' condition."""
    for step in _market_branch(scripts)["sequence"]:
        rpt = step.get("repeat")
        if not rpt:
            continue
        for inner in rpt["sequence"]:
            if "if" in inner:
                return inner["if"][0]["value_template"]
    raise AssertionError("retry loop must contain a verification condition")


def render_vars(scripts, pct):
    """Render the variables block in order with a stubbed states(), like HA does."""
    env = jinja2.Environment()
    env.globals["states"] = lambda entity_id: str(pct)
    ctx = {}
    for name, tmpl in _vars_block(scripts).items():
        if not isinstance(tmpl, str):
            ctx[name] = tmpl  # plain YAML literal, e.g. `target_bri_pct: 55`
            continue
        ctx[name] = _native(env.from_string(tmpl).render(**ctx))
    return ctx


# ---- brightness no longer carries information ----
def test_brightness_is_constant_55_everywhere(scripts):
    for pct in (-9, -4, -1, -0.05, 0, 0.05, 1, 4, 9):
        assert render_vars(scripts, pct)["target_bri_pct"] == 55, \
            f"brightness must be a constant 55 at pct={pct}"


# ---- saturation carries magnitude ----
def test_saturation_floor_is_40(scripts):
    assert render_vars(scripts, 0.1)["target_sat"] >= 40, \
        "smallest non-flat move must still be saturated enough to read direction"


def test_saturation_reaches_100_at_4_percent(scripts):
    assert render_vars(scripts, 4)["target_sat"] == 100
    assert render_vars(scripts, -4)["target_sat"] == 100


def test_saturation_clamps_beyond_4_percent(scripts):
    assert render_vars(scripts, 10)["target_sat"] == 100
    assert render_vars(scripts, -10)["target_sat"] == 100


def test_saturation_is_monotonic_in_move_size(scripts):
    sats = [render_vars(scripts, p)["target_sat"] for p in (0.1, 0.5, 1, 2, 3, 4)]
    assert sats == sorted(sats), f"saturation must rise with move size, got {sats}"
    assert len(set(sats)) > 1, "saturation must actually vary, not be pinned"


def test_saturation_is_symmetric_up_and_down(scripts):
    for p in (0.5, 1, 2, 3):
        assert render_vars(scripts, p)["target_sat"] == render_vars(scripts, -p)["target_sat"]


# ---- hue carries direction only ----
def test_hue_encodes_direction_and_never_magnitude(scripts):
    for p in (0.1, 1, 4, 10):
        assert render_vars(scripts, p)["target_hue"] == 120, "up must be green"
        assert render_vars(scripts, -p)["target_hue"] == 0, "down must be red"


# ---- flat day ----
def test_flat_day_is_amber_at_full_brightness(scripts):
    v = render_vars(scripts, 0.05)
    assert v["target_hue"] == 40, "flat is amber"
    assert v["target_sat"] == 35
    assert v["target_bri_pct"] == 55, "flat is NOT encoded as dim any more"


def test_flat_flag_is_a_real_boolean(scripts):
    """If `flat` rendered as the string 'False' it would be truthy and every day
    would come out amber. HA native-types template results; depend on it correctly."""
    v = render_vars(scripts, 2.0)
    assert v["flat"] is False
    assert v["target_hue"] == 120, "a +2% day must be green, not the flat amber"


def test_hs_pairs_hue_and_saturation(scripts):
    v = render_vars(scripts, -2.0)
    assert list(v["target_hs"]) == [v["target_hue"], v["target_sat"]]


# ---- verification must cover all three channels ----
def test_verification_checks_hue_saturation_and_brightness(scripts):
    t = _verify_template(scripts)
    assert "hs_color" in t and "target_hue" in t and "target_sat" in t, \
        "must verify the channels that now carry the signal"
    assert "brightness" in t and "target_bri_255" in t, (
        "brightness must STAY in the check: script.sofi_heartbeat hands off at "
        "sat 100 / 20% brightness, so on a >=4% day hue+sat already match and a "
        "hue+sat-only check would stop early, stranding the bulb at the burst's tail"
    )


def test_verification_handles_red_hue_wraparound(scripts):
    t = _verify_template(scripts)
    assert "360" in t, \
        "red is reported as 0 OR 359.x — hue distance must be circular, else every "
        "down-day render burns all 3 retries and never confirms"


def test_bri_255_still_derived_from_bri_pct(scripts):
    assert render_vars(scripts, 1.0)["target_bri_255"] == 140  # 55% of 255


# ---- the lub-dub heartbeat is out of scope and must stay untouched ----
def test_heartbeat_is_independent_of_resting_encoding(scripts):
    hb = json.dumps(scripts["sofi_heartbeat"])
    assert "target_sat" not in hb and "target_bri_pct" not in hb, \
        "heartbeat must not read the resting-tint variables"
    assert "[hue | int, 100]" in hb, "beats stay at full saturation"
    assert BULB in hb

git add tests/requirements.txt tests/test_sofi_tint.py
git commit -m "test(sofi): cover saturation-encoded tint math and 3-channel verify"

# SOFI Ticker — resting appearance (single source). Tints bulb_2 by SOFI's % change vs
# previous close during market hours: hue is DIRECTION only (green up / red down) and
# SATURATION carries magnitude (40 → 100 across 0 → ±4%), with brightness held constant
# at 55%. Amber when flat. Off outside 9:30-16:00 ET weekdays. Magnitude used to ride on
# brightness, which rendered small moves nearly black (#001d00 at +0.1%) — see
# docs/superpowers/specs/2026-07-24-sofi-ticker-saturation-tint-design.md.
# The Sengled is Matter and occasionally times out ("Peer no longer responding"), so each
# write retries up to 3× until the bulb reports hue AND saturation AND brightness on
# target. All three matter: brightness alone is inert now that it is constant, but
# dropping it would let a post-heartbeat render stop early and strand the bulb at the
# burst's 20% tail on a ≥4% day (hue+sat already match at hand-off). Hue comparison is
# circular because the bulb reports red as 0 or 359.x. Called by automations.yaml §41
# (/5 tick, start, presence-return) and by script.sofi_heartbeat (to settle after a
# burst). transition: is a no-op on this bulb.

            - variables:
                pct: "{{ states('sensor.sofi_change_pct') | float(0) }}"
                flat: "{{ (pct | abs) < 0.1 }}"
                target_hue: "{{ 40 if flat else (120 if pct >= 0 else 0) }}"
                target_sat: >-
                  {{ 35 if flat else (40 + ([pct | abs, 4] | min) / 4 * 60) | round(0) | int }}
                target_hs: "{{ [target_hue, target_sat] }}"
                target_bri_pct: 55
                target_bri_255: "{{ ((target_bri_pct | float) * 255 / 100) | round(0) | int }}"

                  - if:
                      - condition: template
                        value_template: >-
                          {% set b = 'light.louis_office_sengled_a19_bulb_2' %}
                          {% set hs = state_attr(b, 'hs_color') %}
                          {% set dh = ((hs[0] | float(0)) - target_hue) | abs if hs else 999 %}
                          {{ is_state(b, 'on') and hs is not none
                             and ([dh, 360 - dh] | min) < 10
                             and (((hs[1] | float(0)) - target_sat) | abs) < 8
                             and (((state_attr(b, 'brightness') | int(0)) - target_bri_255) | abs) < 20 }}
                    then:
                      - stop: "SOFI bulb applied"

git add scripts.yaml
git commit -m "feat(sofi): encode ticker magnitude as saturation, not brightness

Sat 40->100 across 0->±4% at a constant 55% brightness; hue stays binary
for direction. A +0.1% day rendered #001d00 (near-black) before — the
bulb was only legible on dramatic days.

Verification now checks hue+saturation+brightness together: brightness
alone is inert under a constant target, but dropping it would strand the
bulb at the heartbeat's 20% tail on >=4% days. Circular hue distance
handles the bulb reporting red as 0 or 359.x."

- 🟢 **Green** when the stock is **up** on the day — deeper, brighter green the more it's up.
- 🔴 **Red** when it's **down** — deeper red the more it's down.

- 🟢 **Green** when the stock is **up** on the day — a pale sage green for a small gain, deepening to a vivid pure green the more it's up.
- 🔴 **Red** when it's **down** — a soft dusty rose for a small dip, deepening to a vivid pure red the more it's down.
- 🟡 **Amber** when the day is flat (less than 0.1% either way).

The bulb stays the same brightness all day — it's the **richness of the colour**, not how bright it is, that tells you how big the move is.

git add CLAUDE.md docs/lighting.md docs/automations.md
git commit -m "docs(sofi): describe saturation-encoded ticker magnitude"

git push

for P in -4.5 -2 -0.05 0 0.05 2 4.5; do
  echo -n "pct=$P -> "
  curl -sf -X POST -H "Authorization: Bearer $HA_TOKEN" \
    -H "Content-Type: application/json" \
    -d "{\"template\":\"{% set pct = $P %}{% set flat = (pct|abs) < 0.1 %}hue={{ 40 if flat else (120 if pct >= 0 else 0) }} sat={{ 35 if flat else (40 + ([pct|abs,4]|min)/4*60)|round(0)|int }}\"}" \
    "$HA_URL/api/template"; echo
done

curl -sf -X POST -H "Authorization: Bearer $HA_TOKEN" \
  -H "Content-Type: application/json" -d '{"entity_id":"script.sofi_ticker_render"}' \
  "$HA_URL/api/services/script/turn_on" >/dev/null
sleep 5
curl -sf -H "Authorization: Bearer $HA_TOKEN" \
  "$HA_URL/api/states/light.louis_office_sengled_a19_bulb_2" \
  | python3 -c "import sys,json;d=json.load(sys.stdin);a=d['attributes'];print('state',d['state'],'hs',a.get('hs_color'),'bri',a.get('brightness'))"

curl -sf -X POST -H "Authorization: Bearer $HA_TOKEN" -H "Content-Type: application/json" \
  -d '{"entity_id":"light.louis_office_sengled_a19_bulb_2","hs_color":[0,80],"brightness_pct":55}' \
  "$HA_URL/api/services/light/turn_on" >/dev/null
sleep 2
curl -sf -H "Authorization: Bearer $HA_TOKEN" \
  "$HA_URL/api/states/light.louis_office_sengled_a19_bulb_2" \
  | python3 -c "import sys,json;print(json.load(sys.stdin)['attributes'].get('hs_color'))"

curl -sf -X POST -H "Authorization: Bearer $HA_TOKEN" -H "Content-Type: application/json" \
  -d '{"entity_id":"script.sofi_heartbeat","variables":{"pairs":2,"hue":120}}' \
  "$HA_URL/api/services/script/turn_on" >/dev/null
sleep 15
curl -sf -H "Authorization: Bearer $HA_TOKEN" \
  "$HA_URL/api/states/light.louis_office_sengled_a19_bulb_2" \
  | python3 -c "import sys,json;a=json.load(sys.stdin)['attributes'];print('hs',a.get('hs_color'),'bri',a.get('brightness'))"