# Home Assistant Tools for Open WebUI

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

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

### Управление (`smart`)
- Свет (вкл/выкл, яркость, цветовая температура)
- Розетки и выключатели
- Климат (температура, режимы нагрев/охлаждение)
- Медиа (плей/пауза, громкость, переключение треков)
- Шторы и жалюзи
- Замки
- Вентиляторы
- Роботы-пылесосы
- Сценарии и скрипты

### Мониторинг (`smart` — ответы на вопросы)
- Какие окна/двери открыты
- Что горит лишнего
- Какая температура в комнатах
- Какие батарейки садятся
- Что сейчас играет
- Кто дома

### Диагностика (`list_devices`)
- Полный список устройств по доменам
- Фильтр по `device_class` (door, window, motion, battery, ...)
- Фильтр по состоянию (`on`, `off`, `open`, `closed`, ...)
- Скрытие `unavailable` / `unknown`
- Спецкатегория `domain="window_door"` для окон и дверей

## Установка

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

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%
уютный свет в спальне
```

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

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

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

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

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

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

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

- **v2.3.0** — добавлен инструмент `list_devices` для диагностики и инвентаризации
- **v2.2.2** — восстановлен полный код после повреждения при обновлении
- **v2.2.1** — HTTPS по умолчанию, verify_ssl в Valves
- **v2.2.0** — мониторинг (окна, свет, климат, батарейки, медиа, присутствие), dry-run, ретраи, кэш
- **v2.0.0** — базовое управление светом, климатом, медиа, шторами

## Лицензия

MIT