HomeAssistant PyScript Converter

Converts Home Assistant YAML automations to pyscript, a Python scripting framework for HA that uses decorators instead of YAML automation declarations. This uses an AI to accelerate the conversion for complex setups.

Prerequisites

1. Sync IDE stubs and automations

Go to HA Developer Tools → Actions and run pyscript.generate_stubs, then sync to your machine:

rsync -rv ha:config/pyscript/modules/stubs/ modules/stubs
rsync -rv ha:/root/config/automations.yaml ./originals/

At runtime the pyscript interpreter ignores imports whose top-level package is stubs, so you can safely add from stubs.pyscript_builtins import ... lines for type hints without affecting execution.

2. Generate Entity ID lookup

Go to HA Developer Tools → Template and render this template, then save the output as originals/entity_ids.csv:

{% for entity in states %}
{{ entity.entity_id }}, {{ device_id(entity.entity_id) }}
{%- endfor %}

Usage

Run the skill:

/ha-pyscript-converter

The skill:

1. Runs analyze_automations.py to cluster automations by shared entities
2. Guides grouping decisions (one file per room/system)
3. Converts each group to a .py file, merging related automations into single functions

How it works

scripts/analyze_automations.py:

1. Parses originals/automations.yaml
2. Clusters automations by shared trigger/target entities using union-find
3. Generates pyscript skeleton code for each group (decorators, conditions as guards, actions, task.sleep for delays, if/elif/else for choose)
4. Marks device UUIDs and ZHA commands with # TODO where human verification is needed
5. Writes one .py skeleton file per cluster into tmp/

Reference files used during conversion:

• references/patterns.md — Complex pattern examples: toggle pairs, door sensors, multi-device buttons, timer patterns, light level dispatch, ZHA button identification, motion-activated lighting, and more
• references/trigger-mapping.md — Exhaustive before/after mapping tables for every trigger type (state, numeric_state, time, time_pattern, sun, event, ZHA), condition type, and action type

Post-conversion

Resolve TODOs

Go through the generated # TODO comments. ZHA event IDs require manual lookup — check the event logger filtering for zha_event. If you see this in the logs, the event trigger type is wrong:

[custom_components.pyscript.trigger] trigger file.gaurav.gaurav_light_button_alt got event trigger, but not active
[custom_components.pyscript.trigger] trigger file.gaurav.gaurav_light_button_alt waiting for state change or event

Deploy

rsync -rv ./pyscript/ "ha:/root/config/pyscript"

Then reload pyscript via HA Developer Tools → Actions → pyscript.reload. You must do this when adding a new file.

Clean up

Once converted, you can delete automations.yaml from HA to disable the old automations.