home-assistant-tools/README.md

# Home Assistant Tools for Open WebUI

Инструменты для управления умным домом через Home Assistant REST API с интерпретацией естественного языка.

## Возможности

### Управление (`smart`)
- Свет (вкл/выкл, яркость, цветовая температура) — поддержка Yeelight LED射灯 и обычных ламп
- Розетки, реле, выключатели — ёлка, гирлянда, ТВ
- Климат (температура, режимы нагрев/охлаждение)
- Медиа (плей/пауза, громкость, переключение треков)
- Шторы и жалюзи
- Замки
- Вентиляторы
- Роботы-пылесосы
- Кнопки (button.press)
- Сцены (scene.turn_on) и скрипты
- **Переименование сущностей** (NL: «переименуй сертификат в Обновление SSL»)
- **Включение/выключение автоматизаций** (NL: «выключи автоматизацию Гирлянда»)

### Мониторинг (`smart` — ответы на вопросы)
- Какие окна/двери открыты (с показом «Неизвестно»)
- Что горит лишнего
- Какая температура в комнатах (только реальные термометры)
- Качество воздуха (TVOC, CO2, PM2.5/10, влажность)
- Где есть движение прямо сейчас
- Какие батарейки садятся
- Что сейчас играет
- Кто дома
- **Что в розетках включено** (без sub-entities типа Power outage memory)
- **Какие сцены есть** (с временем последней активации)
- **Системный статус** (бэкапы, обновления, ноды, мосты)
- Общий отчёт одной фразой

### Диагностика (`list_devices`)
- Полный список устройств по доменам
- Фильтр по `device_class` (door, window, motion, battery, ...)
- Фильтр по состоянию (`on`, `off`, `open`, `closed`, `unavailable`, ...)
- Скрытие `unavailable` / `unknown`
- **Фильтр sub-entities** (`skip_sub_entities=True`) — убирает служебные Power outage memory, Interlock и т.п.
- Спецкатегория `domain="window_door"` для окон и дверей (строгий фильтр)
- NL-маршрутизация: «покажи все binary_sensor» → `list_devices(domain="binary_sensor")`

### Управление автоматизациями (отдельные инструменты)
- `rename_entity` — переименовать любую сущность
- `toggle_automation` — включить/выключить автоматизацию
- `trigger_automation` — запустить автоматизацию вручную

## Установка

### Просто скопировать

1. Открой файл в Gitea:  
   https://gitea.nasweb.ru/host/home-assistant-tools/src/branch/main/home_assistant_tools.py

2. Нажми кнопку **Raw** (справа вверху) — откроется plain text

3. Скопируй всё (`Ctrl+A` → `Ctrl+C`)

4. В Open WebUI: **Workspace → Tools → + Новый инструмент**

5. Вставь код (`Ctrl+V` или долгое нажатие → "Вставить") и сохрани

### Создание токена Home Assistant

1. Откройте HA (https://ha.nasweb.ru) → **Профиль** (левый нижний угол)
2. Прокрутите вниз до **Long-Lived Access Tokens**
3. **Create Token**, имя — `open-webui`
4. **Скопируйте токен** (покажется один раз)

## Настройка Valves

После импорта инструмента откройте его настройки (⚙️) и укажи:

| Параметр | Значение | По умолчанию |
|---|---|---|
| `ha_url` | URL вашего HA | `https://ha.nasweb.ru` |
| `ha_token` | Long-Lived Token из шага выше | (пусто) |
| `verify_ssl` | Проверять SSL: `false` для самоподписанных | `false` |
| `request_timeout` | Таймаут HTTP, сек | `10` |
| `max_retries` | Количество ретраев | `2` |
| `cache_ttl` | TTL кэша состояний, сек | `5` |
| `confirm_global_actions` | Спрашивать подтверждение для «выключи весь свет» | `true` |
| `dry_run` | Только показывать, не выполнять | `false` |

## Включение для пользователя

Open WebUI → **Settings → Interface → Tools** → включите `Home Assistant Smart Control`.

## Примеры команд

### Управление
```
включи свет в спальне
выключи весь свет
поставь 23 градуса в детской
открой шторы в гостиной
пауза музыки
громче
запусти сцену вечерний отдых
включи свет на 50%
уютный свет в спальне
нажми кнопку в спальне
включи ёлку
включи гирлянду
включи ТВ в спальне
```

### Управление автоматизациями
```
переименуй сертификат в Обновление SSL
переименуй automation.сертификат в Обновление SSL
выключи автоматизацию Гирлянда крыльцо
включи автоматизацию Свет в спальне
триггерни автоматизацию Вентиляция душевая
```

### Мониторинг
```
какие окна открыты?
что горит лишнего?
какая температура в спальне?
как воздух в квартире?
где сейчас движение?
батарейки садятся?
кто дома?
что в розетках включено?
какие сцены есть?
как система? есть обновления?
что сейчас играет?
отчёт по дому
```

### Диагностика (отдельный инструмент `list_devices`)

LLM может вызвать инструмент `list_devices` с параметрами, например:

```
list_devices()                                    # все устройства
list_devices(domain="binary_sensor")               # все бинарные датчики
list_devices(domain="window_door")                 # только окна/двери
list_devices(domain="switch", skip_sub_entities=True)  # только реальные розетки
list_devices(device_class="battery")               # только батарейки
list_devices(only_with_state="unavailable")        # все offline
list_devices(show_unavailable=False)               # скрыть offline
```

Или попросить LLM в чате:
```
покажи все binary_sensor
список устройств
какие устройства есть в HA?
```

## Безопасность

- Токен HA хранится в **Valves** Open WebUI, не в коде
- Глобальные команды («выключи весь свет») требуют подтверждения
- Ошибки на одной сущности не валят весь сценарий
- HTTP-запросы с ретраями и таймаутами
- Поддержка HTTPS с опцией отключения проверки сертификата

## Версионирование

- **v2.5.3** — поддержка Yeelight LED射灯, ёлка, гирлянда, ТВ; фильтр sub-entities в switch; мониторинг сцен; больше имён людей
- **v2.5.2** — фикс порядка блоков, фикс форматирования, мониторинг розеток, системный статус, сцены
- **v2.5.1** — строгий фильтр окон/дверей только по device_class
- **v2.5.0** — `rename_entity`, `toggle_automation`, `trigger_automation` + NL-маршрутизация
- **v2.4.0** — мониторинг воздуха, движения, исправлен баг батареек, маршрутизация «покажи», кнопки, общий «отчёт»
- **v2.3.0** — добавлен инструмент `list_devices`
- **v2.2.2** — восстановлен полный код
- **v2.2.1** — HTTPS, verify_ssl
- **v2.2.0** — мониторинг, dry-run, ретраи, кэш
- **v2.0.0** — базовое управление

## Лицензия

MIT