-### Конфигурация
+### YandexGPT
+Быстрый старт
+
+Создайте сервисный аккаунт с ролью `ai.languageModels.user`
+Для создания аккаунта потребуется привязка карты.
+Создайте API ключ
+Идентификатор каталога (Folder ID) можно узнать пройдя по ссылке
+
+### OpenAI
+Для генерации ключа проследуйте по ссылке https://platform.openai.com/account/api-keys
+
+## Конфигурация
+
+* _Темплейт промпта_ (template, Home Assistant `template`)
+
+Системное сообщение, настраивающее модель и задающее исходное поведение.
+Значение по умолчанию является лишь примером, взятым из офицальной интеграции OpenAI Conversation
+Рекомендуется его изменить под собственные нужды.
+
+* _Модель_ (model, `string`)
+
+Модели генерации текста в рамках выбранной LLM. Каждая модель может иметь свои тарифы.
+В настоящее время выбор модели не поддерживается.
+
+* _Температура_ (temperature, `float`)
+
+Температура выборки. Значение температуры должно быть не меньше ноля. Чем выше значение, тем более случайным будет ответ модели. При значениях температуры больше двух, набор токенов в ответе модели может отличаться избыточной случайностью.
+Значение по умолчанию зависит от выбранной модели
+
+* Максимум токенов (max_tokens, int)
-* Темплейт промпта
-* Модель
+Максимальное количество токенов, которые будут использованы для создания ответов.
+В настоящее время не поддерживается, используются настройки модели по умолчанию.
## Использование в качестве диалоговой системы
Создайте и настройте новый голосовой ассистент:
diff --git a/custom_components/gigachain/__init__.py b/custom_components/gigachain/__init__.py
index 77c5de9..89a2348 100644
--- a/custom_components/gigachain/__init__.py
+++ b/custom_components/gigachain/__init__.py
@@ -10,11 +10,18 @@
)
from homeassistant.components.conversation import AgentManager, agent
from typing import Literal
-from langchain_community.chat_models import GigaChat
+from langchain_community.chat_models import GigaChat, ChatYandexGPT, ChatOpenAI
from langchain.schema import AIMessage, HumanMessage, SystemMessage
from homeassistant.util import ulid
from .const import (
DOMAIN,
+ CONF_ENGINE,
+ CONF_TEMPERATURE,
+ DEFAULT_CONF_TEMPERATURE,
+ CONF_CHAT_MODEL,
+ DEFAULT_CHAT_MODEL,
+ CONF_CHAT_MODEL,
+ CONF_FOLDER_ID,
CONF_API_KEY,
CONF_CHAT_MODEL,
DEFAULT_CHAT_MODEL,
@@ -25,9 +32,29 @@
LOGGER = logging.getLogger(__name__)
+async def update_listener(hass: HomeAssistant, entry: ConfigEntry) -> None:
+ """Update listener."""
+ await hass.config_entries.async_reload(entry.entry_id)
+
async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
"""Initialize GigaChain."""
- client = GigaChat(credentials=entry.data[CONF_API_KEY], verify_ssl_certs=False)
+ temperature = entry.options.get(CONF_TEMPERATURE, DEFAULT_CONF_TEMPERATURE)
+ engine = entry.data.get(CONF_ENGINE) or "gigachat"
+ entry.async_on_unload(entry.add_update_listener(update_listener))
+ if engine == 'gigachat':
+ client = GigaChat(temperature=temperature,
+ model='GigaChat:latest',
+ verbose=True,
+ credentials=entry.data[CONF_API_KEY],
+ verify_ssl_certs=False)
+ elif engine == 'yandexgpt':
+ client = ChatYandexGPT(temperature=temperature,
+ api_key=entry.data[CONF_API_KEY],
+ folder_id = entry.data[CONF_FOLDER_ID])
+ else:
+ client = ChatOpenAI(model="gpt-3.5-turbo",
+ temperature=temperature,
+ openai_api_key=entry.data[CONF_API_KEY])
hass.data.setdefault(DOMAIN, {})[entry.entry_id] = client
conversation.async_set_agent(hass, entry, GigaChatAI(hass, entry))
return True
@@ -55,7 +82,6 @@ async def async_process(
) -> agent.ConversationResult:
"""Process a sentence."""
raw_prompt = self.entry.options.get(CONF_PROMPT, DEFAULT_PROMPT)
- model = self.entry.options.get(CONF_CHAT_MODEL, DEFAULT_CHAT_MODEL)
if user_input.conversation_id in self.history:
conversation_id = user_input.conversation_id
messages = self.history[conversation_id]
@@ -70,8 +96,6 @@ async def async_process(
messages.append(HumanMessage(content=user_input.text))
client = self.hass.data[DOMAIN][self.entry.entry_id]
- client.model = model
-
res = client(messages)
messages.append(res)
self.history[conversation_id] = messages
diff --git a/custom_components/gigachain/__pycache__/__init__.cpython-312.pyc b/custom_components/gigachain/__pycache__/__init__.cpython-312.pyc
deleted file mode 100644
index f53ea5036c979e4508eb6b80f8970ab9d831e4b5..0000000000000000000000000000000000000000
GIT binary patch
literal 0
HcmV?d00001
literal 5582
zcma)ATW=f372YM6+
+
+
+ 
+
+
+
+
+# Компонент GigaChain для Home Assistant
+[](https://github.com/custom-components/hacs)
+[](https://github.com/gritaro/gigachain/actions/workflows/hacs.yaml)
+[](https://github.com/gritaro/gigachain/actions/workflows/hassfest.yaml)
+[](https://github.com/gritaro/gigachain)
+[](https://github.com/gritaro/gigachain/releases/latest)
+[](https://github.com/gritaro/gigachain/releases)
+
+Компонент реализует диалоговую систему Home Assistant для использования с языковыми моделями, поддерживаемыми фреймворком GigaChain.
+В настоящее время поддерживаются интеграции с LMM:
+* [GigaChat](#GigaChat) (русскоязычная (но не только) нейросеть от Сбера)
+* [YandexGPT](#YandexGPT)
+* [OpenAI](#OpenAI) ака ChatGPT (не тестируется)
+
+## Установка
+Устанавливается как и любая HACS интеграция.
+
+### Необходимые требования
+Для использования интеграции вам понадобится Home Assistant с установленным [HACS](https://hacs.xyz/)
+
+### Установка с использованием HACS
+Найдите GigaChain в магазине HACS. Если интеграция не находится в магазине HACS, вы можете [добавить этот url как пользовательский репозиторий HACS](https://hacs.xyz/docs/faq/custom_repositories).
+
+[](https://github.com/gritaro/gigachain)
+
+Перезапустите Home Assistant.
+
+## Добавление интеграции
+
+[](https://my.home-assistant.io/redirect/brand/?brand=+GigaChain)
+
+После добавления настройте интеграцию.
+
+## Настройки
+### GigaChat
+### Авторизация запросов к GigaChat
+Для авторизации запросов к GigaChat вам понадобится получить *авторизационные данные* для работы с GigaChat API.
+
+> [!NOTE]
+> О том как получить авторизационные данные для доступа к GigaChat читайте в [официальной документации](https://developers.sber.ru/docs/ru/gigachat/api/integration).
+>
+>
+> [!NOTE]
+> Сертификаты НУЦ Минцифры устанавливать не нужно
+>
+
+
+
+
+ 🦜️🔗 GigaChain (GigaChat + LangChain)
+
+
+### YandexGPT
+Быстрый старт
+
+Создайте сервисный аккаунт с ролью `ai.languageModels.user`.
+Для создания аккаунта потребуется привязка карты. С карты будет снята и возвращена символическая сумма (11 RUB).
+
+Создайте API ключ.
+Идентификатор каталога (Folder ID) можно узнать пройдя по ссылке.
+
+### OpenAI
+Для генерации ключа проследуйте по ссылке https://platform.openai.com/account/api-keys
+
+## Конфигурация
+
+* _Темплейт промпта_ (template, Home Assistant `template`)
+
+Системное сообщение, настраивающее модель и задающее исходное поведение.
+Значение по умолчанию является лишь примером, взятым из офицальной интеграции OpenAI Conversation.
+Рекомендуется его изменить под собственные нужды.
+
+* _Модель_ (model, `string`)
+
+Модели генерации текста в рамках выбранной LLM. Каждая модель может иметь свои тарифы.
+
+* _Температура_ (temperature, `float`)
+
+Температура выборки. Значение температуры должно быть не меньше ноля. Чем выше значение, тем более случайным будет ответ модели. При значениях температуры больше двух, набор токенов в ответе модели может отличаться избыточной случайностью.
+Значение по умолчанию зависит от выбранной модели.
+
+* Максимум токенов (max_tokens, int)
+
+Максимальное количество токенов, которые будут использованы для создания ответов.
+
+## Использование в качестве диалоговой системы
+Создайте и настройте новый голосовой ассистент:
+
+
diff --git a/README.md b/README.md
index d933b3b..f00aac4 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,5 @@
+[](https://github.com/gritaro/gigachain/blob/main/README.md)
+[](https://github.com/gritaro/gigachain/blob/main/README-ru.md)
@@ -8,7 +10,7 @@
-# Компонент GigaChain для Home Assistant
+# GigaChain integration with Home Assistant
[](https://github.com/custom-components/hacs)
[](https://github.com/gritaro/gigachain/actions/workflows/hacs.yaml)
[](https://github.com/gritaro/gigachain/actions/workflows/hassfest.yaml)
@@ -16,77 +18,75 @@
[](https://github.com/gritaro/gigachain/releases/latest)
[](https://github.com/gritaro/gigachain/releases)
-Компонент реализует диалоговую систему Home Assistant для использования с языковыми моделями, поддерживаемыми фреймворком GigaChain.
-В настоящее время поддерживаются интеграции с LMM:
-* [GigaChat](#GigaChat) (русскоязычная нейросеть от Сбера)
+This integration implements Voice Assistant for Home Assistant using GigaChain framework.
+Currently supported LMMs:
+* [GigaChat](#GigaChat) (Sber LLM)
* [YandexGPT](#YandexGPT)
-* [OpenAI](#OpenAI) ака ChatGPT (не тестируется)
+* [OpenAI](#OpenAI) aka ChatGPT (not tested)
-## Установка
-Устанавливается как и любая HACS интеграция.
+## Installation
+Install it like any other HACS integration.
-### Необходимые требования
-Для использования интеграции вам понадобится Home Assistant с установленным [HACS](https://hacs.xyz/)
+### Requirements
+Home Assistant with installed [HACS](https://hacs.xyz/)
-### Установка с использованием HACS
-Найдите GigaChain в магазине HACS. Если интеграция не находится в магазине HACS, вы можете [добавить этот url как пользовательский репозиторий HACS](https://hacs.xyz/docs/faq/custom_repositories).
+### Installation with HACS
+Find GigaChain in HACS store. If you can't find it in store, you could [add this url as HACS custom repository](https://hacs.xyz/docs/faq/custom_repositories).
[](https://github.com/gritaro/gigachain)
-Перезапустите Home Assistant.
+Restart Home Assistant.
-## Добавление интеграции
+## Add Integration
[](https://my.home-assistant.io/redirect/brand/?brand=+GigaChain)
-После добавления настройте интеграцию.
-## Настройки
+After adding, configure integration.
+
+## Settings
### GigaChat
-### Авторизация запросов к GigaChat
-Для авторизации запросов к GigaChat вам понадобится получить *авторизационные данные* для работы с GigaChat API.
+### GigaChat Authorization
+You need to register at https://developers.sber.ru/studio and get an "authorization data" key.
> [!NOTE]
-> О том как получить авторизационные данные для доступа к GigaChat читайте в [официальной документации](https://developers.sber.ru/docs/ru/gigachat/api/integration).
+> You can find more details in GigaChat [official documentation](https://developers.sber.ru/docs/en/gigachat/api/integration).
>
🦜️🔗 GigaChain (GigaChat + LangChain)
### YandexGPT
-Быстрый старт
+Quick start
-Создайте сервисный аккаунт с ролью `ai.languageModels.user`
-Для создания аккаунта потребуется привязка карты.
-Создайте API ключ
-Идентификатор каталога (Folder ID) можно узнать пройдя по ссылке
+Create service account with role `ai.languageModels.user`.
+Create API key.
+You can find Folder ID using this link.
### OpenAI
-Для генерации ключа проследуйте по ссылке https://platform.openai.com/account/api-keys
-
-## Конфигурация
+Create API key here https://platform.openai.com/account/api-keys
-* _Темплейт промпта_ (template, Home Assistant `template`)
+## Configuration
-Системное сообщение, настраивающее модель и задающее исходное поведение.
-Значение по умолчанию является лишь примером, взятым из офицальной интеграции OpenAI Conversation
-Рекомендуется его изменить под собственные нужды.
+* _Prompt template_ (template, Home Assistant `template`)
-* _Модель_ (model, `string`)
+The starting text for the AI language model to generate new text from.
+This text can include information about your Home Assistant instance, devices, and areas and is written using [Home Assistant Templating](https://www.home-assistant.io/docs/configuration/templating/).
+Default value comes from official integration OpenAI Conversation
-Модели генерации текста в рамках выбранной LLM. Каждая модель может иметь свои тарифы.
-В настоящее время выбор модели не поддерживается.
+* _Model_ (model, `string`)
-* _Температура_ (temperature, `float`)
+Language model is used for text generation
-Температура выборки. Значение температуры должно быть не меньше ноля. Чем выше значение, тем более случайным будет ответ модели. При значениях температуры больше двух, набор токенов в ответе модели может отличаться избыточной случайностью.
-Значение по умолчанию зависит от выбранной модели
+* _Temperature_ (temperature, `float`)
-* Максимум токенов (max_tokens, int)
+A value that determines the level of creativity and risk-taking the model should use when generating text.
+A higher temperature means the model is more likely to generate unexpected results, while a lower temperature results in more deterministic results.
+
+* Max Tokens (max_tokens, int)
-Максимальное количество токенов, которые будут использованы для создания ответов.
-В настоящее время не поддерживается, используются настройки модели по умолчанию.
+The maximum number of words or “tokens” that the AI model should generate in its completion of the prompt.
-## Использование в качестве диалоговой системы
-Создайте и настройте новый голосовой ассистент:
+## Using as Voice Assistant
+Create and configure Voice Assistant:
diff --git a/custom_components/gigachain/__init__.py b/custom_components/gigachain/__init__.py
index 33963b4..e27fedd 100644
--- a/custom_components/gigachain/__init__.py
+++ b/custom_components/gigachain/__init__.py
@@ -1,87 +1,72 @@
"""The GigaChain integration."""
+
+import logging
+from typing import Literal
+
from homeassistant.components import conversation
+from homeassistant.components.conversation import agent
from homeassistant.config_entries import ConfigEntry
from homeassistant.const import MATCH_ALL
from homeassistant.core import HomeAssistant
-from homeassistant.helpers import (
- intent,
- template,
-)
-from homeassistant.components.conversation import AgentManager, agent
-
-from typing import Literal
-from langchain_community.chat_models import GigaChat, ChatYandexGPT, ChatOpenAI
-from langchain.schema import AIMessage, HumanMessage, SystemMessage
+from homeassistant.helpers import intent, template
from homeassistant.util import ulid
-from .const import (
- DOMAIN,
- CONF_ENGINE,
- CONF_TEMPERATURE,
- DEFAULT_TEMPERATURE,
- CONF_CHAT_MODEL,
- DEFAULT_CHAT_MODEL,
- CONF_CHAT_MODEL,
- CONF_FOLDER_ID,
- CONF_API_KEY,
- CONF_CHAT_MODEL,
- DEFAULT_CHAT_MODEL,
- CONF_PROMPT,
- DEFAULT_PROMPT
- )
-import logging
+from langchain.schema import BaseMessage, HumanMessage, SystemMessage
+
+from .client_util import get_client
+from .const import (CONF_API_KEY, CONF_CHAT_MODEL, CONF_CHAT_MODEL_USER,
+ CONF_ENGINE, CONF_FOLDER_ID, CONF_MAX_TOKENS,
+ CONF_PROFANITY, CONF_PROMPT, CONF_TEMPERATURE,
+ DEFAULT_CHAT_MODEL, DEFAULT_PROFANITY, DEFAULT_PROMPT,
+ DEFAULT_TEMPERATURE, DOMAIN, ID_GIGACHAT)
LOGGER = logging.getLogger(__name__)
+
async def update_listener(hass: HomeAssistant, entry: ConfigEntry) -> None:
"""Update listener."""
await hass.config_entries.async_reload(entry.entry_id)
+
async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
"""Initialize GigaChain."""
+ engine = entry.data.get(CONF_ENGINE) or ID_GIGACHAT
+ model = entry.options.get(CONF_CHAT_MODEL_USER)
+ if model == " " or model == "" or model is None:
+ model = entry.options.get(CONF_CHAT_MODEL)
temperature = entry.options.get(CONF_TEMPERATURE, DEFAULT_TEMPERATURE)
- model = entry.options.get(CONF_CHAT_MODEL)
- engine = entry.data.get(CONF_ENGINE) or "gigachat"
+ max_tokens = entry.options.get(CONF_MAX_TOKENS)
+
entry.async_on_unload(entry.add_update_listener(update_listener))
- if engine == 'gigachat':
- client = GigaChat(temperature=temperature,
- model=model,
- verbose=True,
- credentials=entry.data[CONF_API_KEY],
- verify_ssl_certs=False)
- elif engine == 'yandexgpt':
- if model == "YandexGPT":
- model_url = "gpt://" + entry.data[CONF_FOLDER_ID] + "/yandexgpt/latest"
- elif model == 'YandexGPT Lite':
- model_url = "gpt://" + entry.data[CONF_FOLDER_ID] + "/yandexgpt-lite/latest"
- elif model == 'Summary':
- model_url = "gpt://" + entry.data[CONF_FOLDER_ID] + "/summarization/latest"
- else:
- model_url = ""
- client = ChatYandexGPT(
- model_uri=model_url,
- temperature=temperature,
- api_key=entry.data[CONF_API_KEY],
- folder_id = entry.data[CONF_FOLDER_ID])
- else:
- client = ChatOpenAI(model=model,
- temperature=temperature,
- openai_api_key=entry.data[CONF_API_KEY])
- hass.data.setdefault(DOMAIN, {})[entry.entry_id] = client
+
+ common_args = {
+ "verbose": False,
+ "model": model
+ }
+ if temperature is not None:
+ common_args["temperature"] = temperature
+ if max_tokens is not None:
+ common_args["max_tokens"] = max_tokens
+
+ _client = await get_client(engine, common_args, entry)
+
+ hass.data.setdefault(DOMAIN, {})[entry.entry_id] = _client
conversation.async_set_agent(hass, entry, GigaChatAI(hass, entry))
return True
+
async def async_unload_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
"""Unload GigaChain."""
hass.data[DOMAIN].pop(entry.entry_id)
conversation.async_unset_agent(hass, entry)
return True
+
class GigaChatAI(conversation.AbstractConversationAgent):
def __init__(self, hass: HomeAssistant, entry: ConfigEntry) -> None:
"""Initialize the agent."""
self.hass = hass
self.entry = entry
- self.history: dict[str, list[dict]] = {}
+ self.history: dict[str, list[BaseMessage]] = {}
@property
def supported_languages(self) -> list[str] | Literal["*"]:
@@ -89,7 +74,7 @@ def supported_languages(self) -> list[str] | Literal["*"]:
return MATCH_ALL
async def async_process(
- self, user_input: agent.ConversationInput
+ self, user_input: agent.ConversationInput
) -> agent.ConversationResult:
"""Process a sentence."""
raw_prompt = self.entry.options.get(CONF_PROMPT, DEFAULT_PROMPT)
@@ -97,25 +82,34 @@ async def async_process(
conversation_id = user_input.conversation_id
messages = self.history[conversation_id]
else:
- conversation_id = ulid.ulid_now()
+ conversation_id = ulid.ulid()
prompt = self._async_generate_prompt(raw_prompt)
- messages = [
- SystemMessage(
- content=prompt
- )
- ]
-
+ messages = [SystemMessage(content=prompt)]
messages.append(HumanMessage(content=user_input.text))
- client = self.hass.data[DOMAIN][self.entry.entry_id]
- res = client(messages)
+ _client = self.hass.data[DOMAIN][self.entry.entry_id]
+
+ try:
+ res = _client(messages)
+ except Exception as err:
+ LOGGER.exception("Unexpected exception %s", type(err))
+ response = intent.IntentResponse(language=user_input.language)
+ response.async_set_error(
+ intent.IntentResponseErrorCode.UNKNOWN,
+ f"Houston we have a problem: {err}",
+ )
+ return agent.ConversationResult(
+ conversation_id=conversation_id, response=response
+ )
+
messages.append(res)
self.history[conversation_id] = messages
+ LOGGER.debug(messages)
response = intent.IntentResponse(language=user_input.language)
response.async_set_speech(res.content)
+ LOGGER.debug(response)
return agent.ConversationResult(
- conversation_id=conversation_id,
- response=response
+ conversation_id=conversation_id, response=response
)
def _async_generate_prompt(self, raw_prompt: str) -> str:
diff --git a/custom_components/gigachain/client_util.py b/custom_components/gigachain/client_util.py
new file mode 100644
index 0000000..c059e92
--- /dev/null
+++ b/custom_components/gigachain/client_util.py
@@ -0,0 +1,63 @@
+import logging
+
+from homeassistant.core import HomeAssistant
+from langchain.schema import SystemMessage
+from langchain_community.chat_models import ChatOpenAI, ChatYandexGPT, GigaChat
+
+from .const import (CONF_API_KEY, CONF_ENGINE, CONF_FOLDER_ID, CONF_PROFANITY,
+ CONF_SKIP_VALIDATION, DEFAULT_PROFANITY, ID_GIGACHAT,
+ ID_YANDEX_GPT)
+
+LOGGER = logging.getLogger(__name__)
+
+
+async def validate_client(
+ hass: HomeAssistant,
+ user_input
+) -> None:
+ if user_input.get(CONF_SKIP_VALIDATION):
+ return
+ engine = user_input.get(CONF_ENGINE) or ID_GIGACHAT
+ if engine == ID_GIGACHAT:
+ credentials = user_input[CONF_API_KEY]
+ client = GigaChat(
+ max_tokens=10,
+ verbose=False,
+ credentials=credentials,
+ verify_ssl_certs=False,
+ )
+ elif engine == ID_YANDEX_GPT:
+ client = ChatYandexGPT(
+ max_tokens=10,
+ max_retries=2,
+ api_key=user_input[CONF_API_KEY],
+ folder_id=user_input[CONF_FOLDER_ID],
+ )
+ else:
+ credentials = user_input[CONF_API_KEY]
+ client = ChatOpenAI(
+ max_tokens=10,
+ model="gpt-3.5-turbo",
+ openai_api_key=credentials,
+ )
+ res = client([SystemMessage(content="{}")])
+ LOGGER.debug(res)
+
+
+async def get_client(engine, common_args, entry):
+ if engine == ID_GIGACHAT:
+ common_args["credentials"] = entry.data[CONF_API_KEY]
+ common_args["verify_ssl_certs"] = False
+ common_args["profanity_check"] = entry.options.get(CONF_PROFANITY, DEFAULT_PROFANITY)
+ client = GigaChat(**common_args)
+ elif engine == ID_YANDEX_GPT:
+ common_args["api_key"] = entry.data[CONF_API_KEY]
+ common_args["folder_id"] = entry.data[CONF_FOLDER_ID]
+ common_args["max_retries"] = 2
+ client = ChatYandexGPT(**common_args)
+ else:
+ if common_args["model"] is None:
+ common_args["model"] = "gpt-3.5-turbo"
+ common_args["openai_api_key"] = entry.data[CONF_API_KEY]
+ client = ChatOpenAI(**common_args)
+ return client
diff --git a/custom_components/gigachain/config_flow.py b/custom_components/gigachain/config_flow.py
index 71906ed..aea81e7 100644
--- a/custom_components/gigachain/config_flow.py
+++ b/custom_components/gigachain/config_flow.py
@@ -1,40 +1,35 @@
"""Config flow for GigaChain integration."""
+
from __future__ import annotations
+import logging
+import types
+from types import MappingProxyType
from typing import Any
import voluptuous as vol
-
+from gigachat.exceptions import ResponseError
from homeassistant import config_entries
from homeassistant.data_entry_flow import FlowResult
-import types
-from types import MappingProxyType
from homeassistant.helpers import selector
-from homeassistant.helpers.selector import (
- TemplateSelector
-)
-import logging
+from homeassistant.helpers.selector import (NumberSelector,
+ NumberSelectorConfig,
+ SelectSelectorMode,
+ TemplateSelector)
+from httpx import ConnectError
+
+from .client_util import validate_client
+from .const import (CONF_API_KEY, CONF_CHAT_MODEL, CONF_CHAT_MODEL_USER,
+ CONF_ENGINE, CONF_ENGINE_OPTIONS, CONF_FOLDER_ID,
+ CONF_MAX_TOKENS, CONF_PROFANITY, CONF_PROMPT,
+ CONF_SKIP_VALIDATION, CONF_TEMPERATURE, DEFAULT_CHAT_MODEL,
+ DEFAULT_MODELS, DEFAULT_PROFANITY, DEFAULT_PROMPT,
+ DEFAULT_SKIP_VALIDATION, DEFAULT_TEMPERATURE, DOMAIN,
+ ID_GIGACHAT, ID_OPENAI, ID_YANDEX_GPT, UNIQUE_ID,
+ UNIQUE_ID_GIGACHAT)
LOGGER = logging.getLogger(__name__)
-from .const import (
- DOMAIN,
- CONF_ENGINE,
- CONF_API_KEY,
- CONF_FOLDER_ID,
- CONF_CHAT_MODEL,
- CONF_TEMPERATURE,
- CONF_ENGINE_OPTIONS,
- CONF_PROMPT,
- CONF_MAX_TOKENS,
- DEFAULT_TEMPERATURE,
- DEFAULT_MODELS,
- DEFAULT_MAX_TOKENS,
- DEFAULT_CHAT_MODEL,
- DEFAULT_PROMPT,
- UNIQUE_ID
-)
-
STEP_USER_SCHEMA = vol.Schema(
{
vol.Required(CONF_ENGINE): selector.SelectSelector(
@@ -42,83 +37,107 @@
),
}
)
-
STEP_API_KEY_SCHEMA = vol.Schema(
{
- vol.Required(CONF_API_KEY): str
+ vol.Required(CONF_API_KEY): str,
+ vol.Optional(
+ CONF_SKIP_VALIDATION, default=DEFAULT_SKIP_VALIDATION
+ ): bool,
}
)
STEP_YANDEXGPT_SCHEMA = vol.Schema(
{
vol.Required(CONF_API_KEY): str,
- vol.Required(CONF_FOLDER_ID): str
+ vol.Required(CONF_FOLDER_ID): str,
+ vol.Optional(
+ CONF_SKIP_VALIDATION, default=DEFAULT_SKIP_VALIDATION
+ ): bool,
}
)
ENGINE_SCHEMA = {
- "gigachat": STEP_API_KEY_SCHEMA,
- "yandexgpt": STEP_YANDEXGPT_SCHEMA,
- "openai": STEP_API_KEY_SCHEMA
+ ID_GIGACHAT: STEP_API_KEY_SCHEMA,
+ ID_YANDEX_GPT: STEP_YANDEXGPT_SCHEMA,
+ ID_OPENAI: STEP_API_KEY_SCHEMA,
}
DEFAULT_OPTIONS = types.MappingProxyType(
{
CONF_PROMPT: DEFAULT_PROMPT,
CONF_CHAT_MODEL: DEFAULT_CHAT_MODEL,
+ CONF_CHAT_MODEL_USER: DEFAULT_CHAT_MODEL,
}
)
+
class ConfigFlow(config_entries.ConfigFlow, domain=DOMAIN):
"""Handle a config flow for GigaChain."""
VERSION = 1
async def async_step_user(
- self, user_input: dict[str, Any] | None = None
+ self, user_input: dict[str, Any] | None = None
) -> FlowResult:
"""Handle the initial step."""
if user_input is None:
- return self.async_show_form(step_id="user",
- data_schema=STEP_USER_SCHEMA)
+ return self.async_show_form(step_id="user", data_schema=STEP_USER_SCHEMA)
engine = user_input[CONF_ENGINE]
unique_id = UNIQUE_ID[engine]
await self.async_set_unique_id(unique_id)
self._abort_if_unique_id_configured()
- return self.async_show_form(
- step_id=engine, data_schema=ENGINE_SCHEMA[engine]
- )
+ return self.async_show_form(step_id=engine, data_schema=ENGINE_SCHEMA[engine])
async def async_step_gigachat(
- self, user_input: dict[str, Any] | None = None) -> FlowResult:
- return await self.common_model_async_step("gigachat", user_input)
+ self, user_input: dict[str, Any] | None = None
+ ) -> FlowResult:
+ return await self.common_model_async_step(ID_GIGACHAT, user_input)
async def async_step_yandexgpt(
- self, user_input: dict[str, Any] | None = None) -> FlowResult:
- return await self.common_model_async_step("yandexgpt", user_input)
+ self, user_input: dict[str, Any] | None = None
+ ) -> FlowResult:
+ return await self.common_model_async_step(ID_YANDEX_GPT, user_input)
- async def async_step_openai(self, user_input: dict[str, Any] | None = None
+ async def async_step_openai(
+ self, user_input: dict[str, Any] | None = None
) -> FlowResult:
- return await self.common_model_async_step("openai", user_input)
+ return await self.common_model_async_step(ID_OPENAI, user_input)
async def common_model_async_step(self, engine, user_input):
if user_input is None:
return self.async_show_form(
step_id=engine, data_schema=ENGINE_SCHEMA[engine]
)
+
+ errors = {}
user_input[CONF_ENGINE] = engine
unique_id = UNIQUE_ID[engine]
- await self.async_set_unique_id(unique_id)
- self._abort_if_unique_id_configured()
- return self.async_create_entry(title=unique_id, data=user_input)
+ try:
+ await validate_client(self.hass, user_input)
+ except ConnectError:
+ errors["base"] = "cannot_connect"
+ except ResponseError:
+ errors["base"] = "invalid_response"
+ except Exception as inst:
+ LOGGER.exception("Unexpected exception %s", type(inst))
+ errors["base"] = "unknown"
+ else:
+ await self.async_set_unique_id(unique_id)
+ self._abort_if_unique_id_configured()
+ return self.async_create_entry(title=unique_id, data=user_input)
+
+ return self.async_show_form(
+ step_id=engine, data_schema=ENGINE_SCHEMA[engine], errors=errors
+ )
@staticmethod
def async_get_options_flow(
- config_entry: config_entries.ConfigEntry,
+ config_entry: config_entries.ConfigEntry,
) -> config_entries.OptionsFlow:
"""Create the options flow."""
return OptionsFlow(config_entry)
+
class OptionsFlow(config_entries.OptionsFlow):
"""GigaChain config flow options handler."""
@@ -127,30 +146,54 @@ def __init__(self, config_entry: config_entries.ConfigEntry) -> None:
self.config_entry = config_entry
async def async_step_init(
- self, user_input: dict[str, Any] | None = None
+ self, user_input: dict[str, Any] | None = None
) -> FlowResult:
"""Manage the options."""
+ errors = {}
+ unique_id = self.config_entry.unique_id
+ schema = common_config_option_schema(
+ unique_id, self.config_entry.options
+ )
if user_input is not None:
- return self.async_create_entry(title=self.config_entry.unique_id, data=user_input)
- schema = common_config_option_schema(self.config_entry.unique_id, self.config_entry.options)
+ model = user_input.get(CONF_CHAT_MODEL_USER)
+ if model == " " or model == "" or model is None:
+ model = user_input.get(CONF_CHAT_MODEL)
+ if model == " " or model == "" or model is None:
+ errors["base"] = "model_required"
+ return self.async_show_form(
+ step_id="init", data_schema=schema, errors=errors
+ )
+
+ return self.async_create_entry(title=unique_id, data=user_input)
+
return self.async_show_form(
step_id="init",
- data_schema=vol.Schema(schema),
+ data_schema=schema,
)
-def common_config_option_schema(unique_id: str, options: MappingProxyType[str, Any]) -> dict:
+
+def common_config_option_schema(
+ unique_id: str, options: MappingProxyType[str, Any]
+) -> vol.Schema:
"""Return a schema for GigaChain completion options."""
if not options:
options = DEFAULT_OPTIONS
- return {
+ schema = vol.Schema({
vol.Optional(
CONF_CHAT_MODEL,
description={
"suggested_value": options.get(CONF_CHAT_MODEL),
- }, default="none",
+ },
+ default="none",
): selector.SelectSelector(
- selector.SelectSelectorConfig(options=DEFAULT_MODELS[unique_id]),
+ selector.SelectSelectorConfig(mode=SelectSelectorMode("dropdown"), options=DEFAULT_MODELS[unique_id]),
),
+ vol.Optional(
+ CONF_CHAT_MODEL_USER,
+ description={
+ "suggested_value": options.get(CONF_CHAT_MODEL_USER)
+ },
+ ): str,
vol.Optional(
CONF_PROMPT,
description={"suggested_value": options[CONF_PROMPT]},
@@ -159,17 +202,25 @@ def common_config_option_schema(unique_id: str, options: MappingProxyType[str, A
vol.Optional(
CONF_TEMPERATURE,
description={
- "suggested_value": options.get(CONF_TEMPERATURE,
- DEFAULT_TEMPERATURE)
+ "suggested_value": options.get(CONF_TEMPERATURE, DEFAULT_TEMPERATURE)
},
default=DEFAULT_TEMPERATURE,
- ): float,
+ ): NumberSelector(NumberSelectorConfig(min=0, max=1, step=0.05)),
vol.Optional(
CONF_MAX_TOKENS,
description={
- "suggested_value": options.get(CONF_MAX_TOKENS,
- DEFAULT_MAX_TOKENS)
+ "suggested_value": options.get(CONF_MAX_TOKENS)
},
- default=DEFAULT_MAX_TOKENS,
- ): int,
- }
+ ): int
+ })
+ if unique_id == UNIQUE_ID_GIGACHAT:
+ schema = schema.extend(
+ {
+ vol.Optional(CONF_PROFANITY,
+ description={
+ "suggested_value": options.get(CONF_PROFANITY, DEFAULT_PROFANITY)
+ },
+ default=DEFAULT_PROFANITY): bool
+ }
+ )
+ return schema
diff --git a/custom_components/gigachain/const.py b/custom_components/gigachain/const.py
index 1601ea6..294d624 100644
--- a/custom_components/gigachain/const.py
+++ b/custom_components/gigachain/const.py
@@ -1,40 +1,19 @@
"""Constants for the GigaChain integration."""
+
from homeassistant.helpers import selector
DOMAIN = "gigachain"
-
-ID_GIGACHAT = "gigachat"
-ID_YANDEX_GPT = "yandexgpt"
-ID_OPENAI = "openai"
-UNIQUE_ID_GIGACHAT = "GigaChat"
-UNIQUE_ID_YANDEX_GPT = "YandexGPT"
-UNIQUE_ID_OPENAI = "OpenAI"
-
-UNIQUE_ID = {
- ID_GIGACHAT: UNIQUE_ID_GIGACHAT,
- ID_YANDEX_GPT: UNIQUE_ID_YANDEX_GPT,
- ID_OPENAI: UNIQUE_ID_OPENAI
-}
-
-CONF_ENGINE_OPTIONS = [
- selector.SelectOptionDict(value=ID_GIGACHAT, label=UNIQUE_ID_GIGACHAT),
- selector.SelectOptionDict(value=ID_YANDEX_GPT, label=UNIQUE_ID_YANDEX_GPT),
- selector.SelectOptionDict(value=ID_OPENAI, label=UNIQUE_ID_OPENAI),
-]
-DEFAULT_MODELS_GIGACHAT = [
- "GigaChat", "GigaChat:latest", "GigaChat-Plus", "GigaChat-Pro"
-]
-DEFAULT_MODELS_YANDEX_GPT = ["YandexGPT", "YandexGPT Lite", "Summary"]
-DEFAULT_MODELS_OPENAI = ["gpt-3.5-turbo"]
-DEFAULT_MODELS = {
- UNIQUE_ID_GIGACHAT: DEFAULT_MODELS_GIGACHAT,
- UNIQUE_ID_YANDEX_GPT: DEFAULT_MODELS_YANDEX_GPT,
- UNIQUE_ID_OPENAI: DEFAULT_MODELS_OPENAI
-}
-CONF_API_KEY = "api_key"
-CONF_FOLDER_ID = "folder_id"
CONF_ENGINE = "engine"
-
+CONF_CHAT_MODEL = "model"
+CONF_CHAT_MODEL_USER = "model_user"
+DEFAULT_CHAT_MODEL = ""
+CONF_TEMPERATURE = "temperature"
+DEFAULT_TEMPERATURE = 0.1
+CONF_PROFANITY = "profanity"
+DEFAULT_PROFANITY = False
+CONF_MAX_TOKENS = "max_tokens"
+CONF_SKIP_VALIDATION = "skip_validation"
+DEFAULT_SKIP_VALIDATION = False
CONF_PROMPT = "prompt"
DEFAULT_PROMPT = """Ты HAL 9000, компьютер из цикла произведений «Космическая одиссея» Артура Кларка, обладающий способностью к самообучению.
Мы находимся в умном доме под управлением системы Home Assistant.
@@ -55,9 +34,63 @@
Когда отвечаешь, обращайся к собеседнику по имени Дэйв.
"""
-CONF_CHAT_MODEL = "model"
-DEFAULT_CHAT_MODEL = ""
-CONF_TEMPERATURE = "temperature"
-DEFAULT_TEMPERATURE = 0.1
-CONF_MAX_TOKENS = "max_tokens"
-DEFAULT_MAX_TOKENS = 250
+"""Models specific constants"""
+
+ID_GIGACHAT = "gigachat"
+ID_YANDEX_GPT = "yandexgpt"
+ID_OPENAI = "openai"
+UNIQUE_ID_GIGACHAT = "GigaChat"
+UNIQUE_ID_YANDEX_GPT = "YandexGPT"
+UNIQUE_ID_OPENAI = "OpenAI"
+
+UNIQUE_ID = {
+ ID_GIGACHAT: UNIQUE_ID_GIGACHAT,
+ ID_YANDEX_GPT: UNIQUE_ID_YANDEX_GPT,
+ ID_OPENAI: UNIQUE_ID_OPENAI,
+}
+
+CONF_ENGINE_OPTIONS = [
+ selector.SelectOptionDict(value=ID_GIGACHAT, label=UNIQUE_ID_GIGACHAT),
+ selector.SelectOptionDict(value=ID_YANDEX_GPT, label=UNIQUE_ID_YANDEX_GPT),
+ selector.SelectOptionDict(value=ID_OPENAI, label=UNIQUE_ID_OPENAI),
+]
+DEFAULT_MODELS_GIGACHAT = [
+ " ",
+ "GigaChat",
+ "GigaChat:latest",
+ "GigaChat-Plus",
+ "GigaChat-Pro",
+]
+DEFAULT_MODELS_YANDEX_GPT = [" ", "YandexGPT", "YandexGPT Lite", "Summary"]
+DEFAULT_MODELS_OPENAI = ["gpt-4",
+ "gpt-4-0314",
+ "gpt-4-0613",
+ "gpt-4-32k",
+ "gpt-4-32k-0314",
+ "gpt-4-32k-0613",
+ "gpt-3.5-turbo",
+ "gpt-3.5-turbo-0301",
+ "gpt-3.5-turbo-0613",
+ "gpt-3.5-turbo-16k",
+ "gpt-3.5-turbo-16k-0613",
+ "gpt-3.5-turbo-instruct",
+ "text-ada-001",
+ "ada",
+ "text-babbage-001",
+ "babbage",
+ "text-curie-001",
+ "curie",
+ "davinci",
+ "text-davinci-003",
+ "text-davinci-002",
+ "code-davinci-002",
+ "code-davinci-001",
+ "code-cushman-002",
+ "code-cushman-001"]
+DEFAULT_MODELS = {
+ UNIQUE_ID_GIGACHAT: DEFAULT_MODELS_GIGACHAT,
+ UNIQUE_ID_YANDEX_GPT: DEFAULT_MODELS_YANDEX_GPT,
+ UNIQUE_ID_OPENAI: DEFAULT_MODELS_OPENAI,
+}
+CONF_API_KEY = "api_key"
+CONF_FOLDER_ID = "folder_id"
diff --git a/custom_components/gigachain/manifest.json b/custom_components/gigachain/manifest.json
index 5d97cfb..e5b6465 100644
--- a/custom_components/gigachain/manifest.json
+++ b/custom_components/gigachain/manifest.json
@@ -13,5 +13,5 @@
"gigachain==0.1.4",
"yandexcloud==0.259.0"
],
- "version": "0.1.3"
+ "version": "0.1.4"
}
diff --git a/custom_components/gigachain/strings.json b/custom_components/gigachain/strings.json
index 3499fa8..cedbf17 100644
--- a/custom_components/gigachain/strings.json
+++ b/custom_components/gigachain/strings.json
@@ -10,36 +10,51 @@
"gigachat": {
"title": "GigaChat configuration",
"data": {
- "api_key": "Auth data"
+ "api_key": "Auth data",
+ "skip_validation": "Skip validation"
}
},
"yandexgpt": {
"title": "YandexGPT configuration",
"data": {
"api_key": "API Key",
- "folder_id": "Folder ID"
+ "folder_id": "Folder ID",
+ "skip_validation": "Skip validation"
}
},
"openai": {
"title": "OpenAI configuration",
"data": {
- "api_key": "API Key"
+ "api_key": "API Key",
+ "skip_validation": "Skip validation"
}
}
},
"abort": {
"already_configured": "Already configured"
+ },
+ "error": {
+ "cannot_connect": "Can not connect",
+ "invalid_response": "Invalid response",
+ "unknown": "Unknown error"
}
},
"options": {
+ "error": {
+ "model_required": "Either Model or Custom Model required"
+ },
"step": {
"init": {
"title": "Model configuration",
"data": {
"prompt": "Prompt Template",
"model": "Completion Model",
+ "model_gigachat": "Custom Model Name (leave empty to use from list above)",
+ "model_yandexgpt": "Custom Model Name (leave empty to use from list above)",
+ "model_openai": "Custom Model Name (leave empty to use from list above)",
"temperature": "Temperature",
- "max_tokens": "Max Tokens"
+ "max_tokens": "Max Tokens",
+ "profanity": "Profanity"
}
}
}
diff --git a/custom_components/gigachain/translations/en.json b/custom_components/gigachain/translations/en.json
index 3499fa8..cedbf17 100644
--- a/custom_components/gigachain/translations/en.json
+++ b/custom_components/gigachain/translations/en.json
@@ -10,36 +10,51 @@
"gigachat": {
"title": "GigaChat configuration",
"data": {
- "api_key": "Auth data"
+ "api_key": "Auth data",
+ "skip_validation": "Skip validation"
}
},
"yandexgpt": {
"title": "YandexGPT configuration",
"data": {
"api_key": "API Key",
- "folder_id": "Folder ID"
+ "folder_id": "Folder ID",
+ "skip_validation": "Skip validation"
}
},
"openai": {
"title": "OpenAI configuration",
"data": {
- "api_key": "API Key"
+ "api_key": "API Key",
+ "skip_validation": "Skip validation"
}
}
},
"abort": {
"already_configured": "Already configured"
+ },
+ "error": {
+ "cannot_connect": "Can not connect",
+ "invalid_response": "Invalid response",
+ "unknown": "Unknown error"
}
},
"options": {
+ "error": {
+ "model_required": "Either Model or Custom Model required"
+ },
"step": {
"init": {
"title": "Model configuration",
"data": {
"prompt": "Prompt Template",
"model": "Completion Model",
+ "model_gigachat": "Custom Model Name (leave empty to use from list above)",
+ "model_yandexgpt": "Custom Model Name (leave empty to use from list above)",
+ "model_openai": "Custom Model Name (leave empty to use from list above)",
"temperature": "Temperature",
- "max_tokens": "Max Tokens"
+ "max_tokens": "Max Tokens",
+ "profanity": "Profanity"
}
}
}
diff --git a/custom_components/gigachain/translations/ru.json b/custom_components/gigachain/translations/ru.json
index c29390a..d67d071 100644
--- a/custom_components/gigachain/translations/ru.json
+++ b/custom_components/gigachain/translations/ru.json
@@ -10,36 +10,51 @@
"gigachat": {
"title": "Конфигурация GigaChat",
"data": {
- "api_key": "Авторизационные данные"
+ "api_key": "Авторизационные данные",
+ "skip_validation": "Skip validation"
}
},
"yandexgpt": {
"title": "Конфигурация YandexGPT",
"data": {
"api_key": "API ключ",
- "folder_id": "Folder ID"
+ "folder_id": "Folder ID",
+ "skip_validation": "Skip validation"
}
},
"openai": {
"title": "Конфигурация OpenAI",
"data": {
- "api_key": "API ключ"
+ "api_key": "API ключ",
+ "skip_validation": "Skip validation"
}
}
},
"abort": {
"already_configured": "Эта модель уже настроена"
+ },
+ "error": {
+ "cannot_connect": "Can not connect",
+ "invalid_response": "Invalid response",
+ "unknown": "Unknown error"
}
},
"options": {
+ "error": {
+ "model_required": "Выберите модель из списка либо задайте свою"
+ },
"step": {
"init": {
"title": "Конфигурация модели",
"data": {
"prompt": "Промпт темплейт",
"model": "Модель",
+ "model_gigachat": "Своё имя модели (оставьте пустым для использования имени из списка)",
+ "model_yandexgpt": "Своё имя модели (оставьте пустым для использования имени из списка)",
+ "model_openai": "Своё имя модели (оставьте пустым для использования имени из списка)",
"temperature": "Температура",
- "max_tokens": "Максимум токенов"
+ "max_tokens": "Максимум токенов",
+ "profanity": "Цензура"
}
}
}
diff --git a/test-model.py b/test-model.py
index 4103abd..09496ca 100644
--- a/test-model.py
+++ b/test-model.py
@@ -1,7 +1,7 @@
from langchain.schema import HumanMessage, SystemMessage
from langchain_community.chat_models import ChatAnyscale
-chat = ChatAnyscale(model="eta-llama/Llama-2-70b-chat-hf", anyscale_api_key="-
-
-
-
-
+[](https://github.com/gritaro/ha-smartchain/blob/main/README.md)
+[](https://github.com/gritaro/ha-smartchain/blob/main/README-ru.md)
-
-
-### YandexGPT
-Быстрый старт
-
-Создайте сервисный аккаунт с ролью `ai.languageModels.user`.
-Для создания аккаунта потребуется привязка карты. С карты будет снята и возвращена символическая сумма (11 RUB).
-
-Создайте API ключ.
-Идентификатор каталога (Folder ID) можно узнать пройдя по ссылке.
-
-### OpenAI
-Для генерации ключа проследуйте по ссылке https://platform.openai.com/account/api-keys
-
-### ~~Anyscale~~
-[~~Зарегистрируйтесь~~](https://app.endpoints.anyscale.com/welcome) ~~и создайте API ключ~~ [~~здесь~~](https://app.endpoints.anyscale.com/credentials) На данный момент не поддерживается.
-
-## Конфигурация
+## Установка
-* _Темплейт промпта_ (template, Home Assistant `template`)
+### Требования
+- Home Assistant с установленным [HACS](https://hacs.xyz/)
-Системное сообщение, настраивающее модель и задающее исходное поведение.
-Значение по умолчанию является лишь примером, взятым из офицальной интеграции OpenAI Conversation.
-Рекомендуется его изменить под собственные нужды.
+### Установка через HACS
+1. Добавьте репозиторий как [пользовательский HACS репозиторий](https://hacs.xyz/docs/faq/custom_repositories)
+2. Найдите "SmartChain" в HACS
+3. Установите и перезапустите Home Assistant
-* _Модель_ (model, `string`)
+## Настройка
-Модели генерации текста в рамках выбранной LLM. Каждая модель может иметь свои тарифы.
+### 1. Добавление интеграции
+**Настройки → Устройства и службы → Добавить интеграцию → SmartChain**
-* _Температура_ (temperature, `float`)
+### 2. Выбор LLM-провайдера
+Выберите GigaChat, YandexGPT или OpenAI и введите API-ключ.
-Температура выборки. Значение температуры должно быть не меньше ноля. Чем выше значение, тем более случайным будет ответ модели. При значениях температуры больше двух, набор токенов в ответе модели может отличаться избыточной случайностью.
-Значение по умолчанию зависит от выбранной модели.
+### 3. Параметры
+- **Модель** — выбор из списка или ввод своего имени модели
+- **Assist API** — управление устройствами через tool calling
+- **Системный промпт** — настройка поведения ассистента (Jinja2)
+- **Температура** — креативность ответов (0.0–1.0)
+- **Макс. токенов** — ограничение длины ответа
+- **История** — включение/отключение памяти диалога
+- **Встроенные команды** — использование нативного процессора команд HA
-* Максимум токенов (max_tokens, `int`)
+### Настройка провайдеров
-Максимальное количество токенов, которые будут использованы для создания ответов.
+#### GigaChat
+Зарегистрируйтесь на [developers.sber.ru](https://developers.sber.ru/studio) и получите авторизационные данные.
-* _Использовать встроенный HA командный процессор_ (process_builtin_sentences, `bool`)
+#### YandexGPT
+Создайте [сервисный аккаунт](https://cloud.yandex.com/ru/docs/iam/operations/sa/create) с ролью `ai.languageModels.user` и [API-ключ](https://cloud.yandex.com/ru/docs/iam/operations/api-key/create).
-Если включено, все фразы сначала будут отдаваться [встроенному в HA процессору шаблонных фраз](https://www.home-assistant.io/voice_control/builtin_sentences).
-Это основное поведение встроенной в Home Assistant диалоговой системы, что позволяет использовать команды вида `включи телевизор в зале`.
-Если фраза не может быть распознана встроенным процессором - она будет передана дальше, выбранной языковой модели.
+#### OpenAI
+Получите API-ключ на [platform.openai.com](https://platform.openai.com/account/api-keys)
-* История сообщений (chat_history, `bool`)
+## Использование
-Если у вашей модели дорогой тариф, либо ваш сценарий использования это позволяет, вы можете отключить историю. В противном случае вся история диалога передаётся в каждом запросе.
+Создайте голосовой ассистент в настройках HA и выберите SmartChain как conversation agent.
-## Использование в качестве диалоговой системы
-Создайте и настройте новый голосовой ассистент:
+## Лицензия
-
+MIT
diff --git a/README.md b/README.md
index dc6d866..68941bf 100644
--- a/README.md
+++ b/README.md
@@ -1,108 +1,73 @@
-[](https://github.com/gritaro/gigachain/blob/main/README.md)
-[](https://github.com/gritaro/gigachain/blob/main/README-ru.md)
-
-
-
+[](https://github.com/gritaro/ha-smartchain/blob/main/README.md)
+[](https://github.com/gritaro/ha-smartchain/blob/main/README-ru.md)
- 🦜️🔗 GigaChain (GigaChat + LangChain)
+
+
-# Компонент GigaChain для Home Assistant
-[](https://hacs.xyz)
-[](https://github.com/gritaro/gigachain/actions/workflows/hacs.yaml)
-[](https://github.com/gritaro/gigachain/actions/workflows/hassfest.yaml)
-[](https://github.com/gritaro/gigachain)
-[](https://github.com/gritaro/gigachain/releases/latest)
-[](https://github.com/gritaro/gigachain/releases)
-
-Компонент реализует диалоговую систему Home Assistant для использования с языковыми моделями, поддерживаемыми фреймворком GigaChain.
-В настоящее время поддерживаются интеграции с LMM:
-* [GigaChat](#GigaChat) (русскоязычная (но не только) нейросеть от Сбера)
-* [YandexGPT](#YandexGPT)
-* [OpenAI](#OpenAI) ака ChatGPT (не тестируется)
-* [~~Anyscale~~](#Anyscale)
-
-## Установка
-Устанавливается как и любая HACS интеграция.
-
-### Необходимые требования
-Для использования интеграции вам понадобится Home Assistant с установленным [HACS](https://hacs.xyz/)
-
-### Установка с использованием HACS
-Найдите GigaChain в магазине HACS. Если интеграция не находится в магазине HACS, вы можете [добавить этот url как пользовательский репозиторий HACS](https://hacs.xyz/docs/faq/custom_repositories).
-
-[](https://github.com/gritaro/gigachain)
+[](https://hacs.xyz)
+[](https://github.com/gritaro/ha-smartchain/releases)
-Перезапустите Home Assistant.
+## Обзор
-## Добавление интеграции
+SmartChain — кастомная интеграция Home Assistant, предоставляющая голосового/текстового ассистента на базе нескольких LLM-провайдеров через LangChain:
-[](https://my.home-assistant.io/redirect/brand/?brand=+GigaChain)
+- **GigaChat** (Сбер) — русскоязычная LLM
+- **YandexGPT** — LLM от Яндекса
+- **OpenAI** — GPT-4.1, GPT-4o, o3, o4-mini
-После добавления настройте интеграцию.
+### Возможности
-## Настройки
-### GigaChat
-### Авторизация запросов к GigaChat
-Для авторизации запросов к GigaChat вам понадобится получить *авторизационные данные* для работы с GigaChat API.
+- **Потоковые ответы** — ответы приходят токен за токеном в реальном времени
+- **Assist API (tool calling)** — управление устройствами HA через LLM (свет, розетки, замки и т.д.)
+- **История диалогов** — многоходовые разговоры с контекстом
+- **Встроенный процессор команд HA** — фоллбек на нативные команды HA
+- **Настраиваемый системный промпт** — Jinja2 шаблоны с контекстом устройств и зон
+- **Несколько LLM-провайдеров** — переключение без потери конфигурации
-> [!NOTE]
-> О том как получить авторизационные данные для доступа к GigaChat читайте в [официальной документации](https://developers.sber.ru/docs/ru/gigachat/api/integration).
->
->
-> [!NOTE]
-> Сертификаты НУЦ Минцифры устанавливать не нужно
->
-
-SmartChain
+Мультипровайдерный LLM-ассистент для Home Assistant
-
-### YandexGPT
-Быстрый старт
-
-Создайте сервисный аккаунт с ролью `ai.languageModels.user`.
-Для создания аккаунта потребуется привязка карты. С карты будет снята и возвращена символическая сумма (11 RUB).
-
-Создайте API ключ.
-Идентификатор каталога (Folder ID) можно узнать пройдя по ссылке.
-
-### OpenAI
-Для генерации ключа проследуйте по ссылке https://platform.openai.com/account/api-keys
-
-### ~~Anyscale~~
-[~~Зарегистрируйтесь~~](https://app.endpoints.anyscale.com/welcome) ~~и создайте API ключ~~ [~~здесь~~](https://app.endpoints.anyscale.com/credentials) На данный момент не поддерживается.
-
-## Конфигурация
+## Установка
-* _Темплейт промпта_ (template, Home Assistant `template`)
+### Требования
+- Home Assistant с установленным [HACS](https://hacs.xyz/)
-Системное сообщение, настраивающее модель и задающее исходное поведение.
-Значение по умолчанию является лишь примером, взятым из офицальной интеграции OpenAI Conversation.
-Рекомендуется его изменить под собственные нужды.
+### Установка через HACS
+1. Добавьте репозиторий как [пользовательский HACS репозиторий](https://hacs.xyz/docs/faq/custom_repositories)
+2. Найдите "SmartChain" в HACS
+3. Установите и перезапустите Home Assistant
-* _Модель_ (model, `string`)
+## Настройка
-Модели генерации текста в рамках выбранной LLM. Каждая модель может иметь свои тарифы.
+### 1. Добавление интеграции
+**Настройки → Устройства и службы → Добавить интеграцию → SmartChain**
-* _Температура_ (temperature, `float`)
+### 2. Выбор LLM-провайдера
+Выберите GigaChat, YandexGPT или OpenAI и введите API-ключ.
-Температура выборки. Значение температуры должно быть не меньше ноля. Чем выше значение, тем более случайным будет ответ модели. При значениях температуры больше двух, набор токенов в ответе модели может отличаться избыточной случайностью.
-Значение по умолчанию зависит от выбранной модели.
+### 3. Параметры
+- **Модель** — выбор из списка или ввод своего имени модели
+- **Assist API** — управление устройствами через tool calling
+- **Системный промпт** — настройка поведения ассистента (Jinja2)
+- **Температура** — креативность ответов (0.0–1.0)
+- **Макс. токенов** — ограничение длины ответа
+- **История** — включение/отключение памяти диалога
+- **Встроенные команды** — использование нативного процессора команд HA
-* Максимум токенов (max_tokens, `int`)
+### Настройка провайдеров
-Максимальное количество токенов, которые будут использованы для создания ответов.
+#### GigaChat
+Зарегистрируйтесь на [developers.sber.ru](https://developers.sber.ru/studio) и получите авторизационные данные.
-* _Использовать встроенный HA командный процессор_ (process_builtin_sentences, `bool`)
+#### YandexGPT
+Создайте [сервисный аккаунт](https://cloud.yandex.com/ru/docs/iam/operations/sa/create) с ролью `ai.languageModels.user` и [API-ключ](https://cloud.yandex.com/ru/docs/iam/operations/api-key/create).
-Если включено, все фразы сначала будут отдаваться [встроенному в HA процессору шаблонных фраз](https://www.home-assistant.io/voice_control/builtin_sentences).
-Это основное поведение встроенной в Home Assistant диалоговой системы, что позволяет использовать команды вида `включи телевизор в зале`.
-Если фраза не может быть распознана встроенным процессором - она будет передана дальше, выбранной языковой модели.
+#### OpenAI
+Получите API-ключ на [platform.openai.com](https://platform.openai.com/account/api-keys)
-* История сообщений (chat_history, `bool`)
+## Использование
-Если у вашей модели дорогой тариф, либо ваш сценарий использования это позволяет, вы можете отключить историю. В противном случае вся история диалога передаётся в каждом запросе.
+Создайте голосовой ассистент в настройках HA и выберите SmartChain как conversation agent.
-## Использование в качестве диалоговой системы
-Создайте и настройте новый голосовой ассистент:
+## Лицензия
-
+MIT
diff --git a/README.md b/README.md
index dc6d866..68941bf 100644
--- a/README.md
+++ b/README.md
@@ -1,108 +1,73 @@
-[](https://github.com/gritaro/gigachain/blob/main/README.md)
-[](https://github.com/gritaro/gigachain/blob/main/README-ru.md)
--
-
-
-
-
+[](https://github.com/gritaro/ha-smartchain/blob/main/README.md)
+[](https://github.com/gritaro/ha-smartchain/blob/main/README-ru.md)
-
-
-### YandexGPT
-Quick start
-
-Create service account with role `ai.languageModels.user`.
-Create API key.
-You can find Folder ID using this link.
+## Installation
-### OpenAI
-Create API key here https://platform.openai.com/account/api-keys
+### Requirements
+- Home Assistant with [HACS](https://hacs.xyz/) installed
-### ~~Anyscale~~
-[~~Register account~~](https://app.endpoints.anyscale.com/welcome) ~~and create API key~~ [~~here~~](https://app.endpoints.anyscale.com/credentials)
-Not supported anymore.
+### Install via HACS
+1. Add this repository as a [custom HACS repository](https://hacs.xyz/docs/faq/custom_repositories)
+2. Search for "SmartChain" in HACS
+3. Install and restart Home Assistant
## Configuration
-* _Prompt template_ (template, Home Assistant `template`)
-
-The starting text for the AI language model to generate new text from.
-This text can include information about your Home Assistant instance, devices, and areas and is written using [Home Assistant Templating](https://www.home-assistant.io/docs/configuration/templating/).
-Default value comes from official integration OpenAI Conversation
-
-* _Model_ (model, `string`)
-
-Language model is used for text generation
+### 1. Add Integration
+Go to **Settings → Devices & Services → Add Integration → SmartChain**
-* _Temperature_ (temperature, `float`)
+### 2. Select LLM Provider
+Choose GigaChat, YandexGPT, or OpenAI and provide API credentials.
-A value that determines the level of creativity and risk-taking the model should use when generating text.
-A higher temperature means the model is more likely to generate unexpected results, while a lower temperature results in more deterministic results.
-
-* Max Tokens (max_tokens, `int`)
+### 3. Configure Options
+- **Model** — select or type custom model name
+- **Assist API** — enable device control via LLM tool calling
+- **System Prompt** — customize the assistant's behavior (Jinja2 template)
+- **Temperature** — control response creativity (0.0–1.0)
+- **Max Tokens** — limit response length
+- **Chat History** — enable/disable multi-turn memory
+- **Builtin Sentences** — use HA's native command processor as fallback
-The maximum number of words or “tokens” that the AI model should generate in its completion of the prompt.
+### Provider Setup
-* _Process HA Builtin Sentences_ (process_builtin_sentences, `bool`)
+#### GigaChat
+Register at [developers.sber.ru](https://developers.sber.ru/studio) and get authorization credentials.
-If enabled, integration first will pass all sentences to [HA built-in sentence processor](https://www.home-assistant.io/voice_control/builtin_sentences).
-This is default behaviour of default Home Assistant Voice Assistant engine which allow you to use commands something like `turn on the living room light`.
-If sentence will not be recognized by HA, it will be passed further to chosen LLM.
+#### YandexGPT
+Create a [service account](https://cloud.yandex.com/en/docs/iam/operations/sa/create) with `ai.languageModels.user` role and generate an [API key](https://cloud.yandex.com/en/docs/iam/operations/api-key/create).
-* Chat History (chat_history, `bool`)
+#### OpenAI
+Get an API key at [platform.openai.com](https://platform.openai.com/account/api-keys)
-Keep all conversation history.
+## Usage
+Create a Voice Assistant in HA settings and select your SmartChain entity as the conversation agent.
-## Using as Voice Assistant
-Create and configure Voice Assistant:
+## License
-
+MIT
diff --git a/TODO.md b/TODO.md
new file mode 100644
index 0000000..44affd5
--- /dev/null
+++ b/TODO.md
@@ -0,0 +1,32 @@
+# SmartChain — TODO
+
+## Phase 1 — Competitive parity
+
+- [x] v0.6 Assist API — device control via tool calling
+- [x] v0.7 Rename GigaChain -> SmartChain + AI Task entity
+- [ ] v0.8.1 Ollama — local models (T-Pro, Qwen, Llama, Home-3B)
+- [ ] v0.8.2 DeepSeek — cheapest cloud provider
+- [ ] v0.8.3 Anthropic — Claude via LangChain
+- [ ] v0.9 Sub-entries — multiple agents with different models/prompts
+
+## Phase 2 — Differentiation
+
+- [ ] v1.0 Vision — camera image analysis (GigaChat 2.0, GPT-4o, Ollama)
+- [ ] v1.1 Image generation — Kandinsky (GigaChat) + YandexART
+- [ ] v1.2 MCP — connect external MCP servers as tools
+- [ ] v1.3 State history — LLM analyzes past events and trends
+
+## Phase 3 — Leadership
+
+- [ ] v1.4 Multi-agent — Dispatcher + specialized agents (LangGraph)
+- [ ] v1.5 Telegram bot — home control via Telegram
+- [ ] v1.6 STT/TTS — Yandex SpeechKit, full voice pipeline
+- [ ] v1.7 Skill system — loadable skills from YAML
+- [ ] v1.8 Prompt caching — token savings on repeated requests
+
+## Technical debt
+
+- [ ] Tests: Options Flow (config_flow)
+- [ ] Test: integration with real ChatLog (not mock)
+- [ ] E2E test: tool calling loop
+- [ ] HACS: verify compatibility and publish
diff --git a/custom_components/gigachain/conversation.py b/custom_components/gigachain/conversation.py
deleted file mode 100644
index 6b5cee9..0000000
--- a/custom_components/gigachain/conversation.py
+++ /dev/null
@@ -1,172 +0,0 @@
-"""Conversation entity for GigaChain integration."""
-
-import logging
-from collections.abc import AsyncIterable
-from typing import Any, Literal
-
-from home_assistant_intents import get_languages
-from homeassistant.components.conversation import (
- ChatLog,
- ConversationEntity,
- ConversationInput,
- ConversationResult,
-)
-from homeassistant.components.conversation.chat_log import (
- AssistantContent,
- SystemContent,
- UserContent,
-)
-from homeassistant.config_entries import ConfigEntry
-from homeassistant.helpers import intent, template
-from homeassistant.helpers.entity_platform import AddEntitiesCallback
-from langchain_core.messages import (
- AIMessage,
- BaseMessage,
- HumanMessage,
- SystemMessage,
-)
-
-from .const import (
- CONF_CHAT_HISTORY,
- CONF_PROCESS_BUILTIN_SENTENCES,
- CONF_PROMPT,
- DEFAULT_CHAT_HISTORY,
- DEFAULT_PROCESS_BUILTIN_SENTENCES,
- DEFAULT_PROMPT,
-)
-
-LOGGER = logging.getLogger(__name__)
-
-
-async def async_setup_entry(
- hass,
- config_entry: ConfigEntry,
- async_add_entities: AddEntitiesCallback,
-) -> None:
- """Set up conversation entity."""
- async_add_entities([GigaChainConversationEntity(config_entry)])
-
-
-class GigaChainConversationEntity(ConversationEntity):
- """GigaChain conversation entity using ConversationEntity API."""
-
- _attr_has_entity_name = True
- _attr_name = None
- _attr_supports_streaming = True
-
- def __init__(self, entry: ConfigEntry) -> None:
- """Initialize the entity."""
- self.entry = entry
- self._attr_unique_id = entry.entry_id
-
- @property
- def supported_languages(self) -> list[str] | Literal["*"]:
- """Return a list of supported languages."""
- return get_languages()
-
- async def _async_handle_message(
- self,
- user_input: ConversationInput,
- chat_log: ChatLog,
- ) -> ConversationResult:
- """Handle a conversation message via ChatLog API."""
- conversation_id = chat_log.conversation_id
-
- # Generate system prompt
- raw_prompt = self.entry.options.get(CONF_PROMPT, DEFAULT_PROMPT)
- prompt = template.Template(raw_prompt, self.hass).async_render(
- {"ha_name": self.hass.config.location_name},
- parse_result=False,
- )
- chat_log.content[0] = SystemContent(content=prompt)
-
- # Convert ChatLog content → LangChain messages for LLM
- chat_history_enabled = self.entry.options.get(
- CONF_CHAT_HISTORY, DEFAULT_CHAT_HISTORY
- )
- if chat_history_enabled:
- messages = _chatlog_to_langchain(chat_log)
- else:
- # Without history: only system prompt + current user message
- messages = [
- SystemMessage(content=prompt),
- HumanMessage(content=user_input.text),
- ]
-
- # Try builtin HA sentence processor first
- use_builtin = self.entry.options.get(
- CONF_PROCESS_BUILTIN_SENTENCES, DEFAULT_PROCESS_BUILTIN_SENTENCES
- )
- if use_builtin:
- from homeassistant.components.conversation import agent_manager
-
- default_agent = agent_manager.async_get_agent(self.hass, None)
- default_response = await default_agent.async_process(user_input)
-
- if default_response.response.intent:
- speech = (
- default_response.response.speech.get("plain", {}).get("speech", "")
- )
- chat_log.async_add_assistant_content_without_tools(
- AssistantContent(
- agent_id=user_input.agent_id,
- content=speech,
- )
- )
- return default_response
-
- # Call LLM with streaming
- client = self.entry.runtime_data
-
- try:
- async for _content in chat_log.async_add_delta_content_stream(
- user_input.agent_id,
- _async_langchain_stream(client, messages),
- ):
- pass
- except Exception as err:
- LOGGER.exception("Unexpected exception %s", type(err))
- response = intent.IntentResponse(language=user_input.language)
- response.async_set_error(
- intent.IntentResponseErrorCode.UNKNOWN,
- f"Houston we have a problem: {err}",
- )
- return ConversationResult(
- conversation_id=conversation_id, response=response
- )
-
- response = intent.IntentResponse(language=user_input.language)
- response.async_set_speech(chat_log.content[-1].content or "")
- return ConversationResult(
- conversation_id=conversation_id, response=response
- )
-
-
-def _chatlog_to_langchain(chat_log: ChatLog) -> list[BaseMessage]:
- """Convert ChatLog content to LangChain message list."""
- messages: list[BaseMessage] = []
- for content in chat_log.content:
- if isinstance(content, SystemContent):
- messages.append(SystemMessage(content=content.content))
- elif isinstance(content, UserContent):
- messages.append(HumanMessage(content=content.content))
- elif isinstance(content, AssistantContent):
- if content.content:
- messages.append(AIMessage(content=content.content))
- return messages
-
-
-async def _async_langchain_stream(
- client: Any, messages: list[BaseMessage]
-) -> AsyncIterable[dict[str, Any]]:
- """Convert LangChain astream chunks to HA delta dicts."""
- first = True
- async for chunk in client.astream(messages):
- delta: dict[str, Any] = {}
- if first:
- delta["role"] = "assistant"
- first = False
- if chunk.content:
- delta["content"] = chunk.content
- if delta:
- yield delta
diff --git a/custom_components/gigachain/__init__.py b/custom_components/smartchain/__init__.py
similarity index 94%
rename from custom_components/gigachain/__init__.py
rename to custom_components/smartchain/__init__.py
index b47c502..47d914b 100644
--- a/custom_components/gigachain/__init__.py
+++ b/custom_components/smartchain/__init__.py
@@ -1,4 +1,4 @@
-"""The GigaChain integration."""
+"""The SmartChain integration."""
import logging
@@ -28,7 +28,7 @@ async def update_listener(hass: HomeAssistant, entry: ConfigEntry) -> None:
async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
- """Initialize GigaChain."""
+ """Initialize SmartChain."""
engine = entry.data.get(CONF_ENGINE) or ID_GIGACHAT
model = entry.options.get(CONF_CHAT_MODEL_USER)
if not model or not model.strip():
@@ -56,5 +56,5 @@ async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
async def async_unload_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
- """Unload GigaChain."""
+ """Unload SmartChain."""
return await hass.config_entries.async_unload_platforms(entry, PLATFORMS)
diff --git a/custom_components/smartchain/ai_task.py b/custom_components/smartchain/ai_task.py
new file mode 100644
index 0000000..52d87ed
--- /dev/null
+++ b/custom_components/smartchain/ai_task.py
@@ -0,0 +1,95 @@
+"""AI Task entity for SmartChain integration."""
+
+import logging
+from typing import Any
+
+from homeassistant.components import ai_task, conversation
+from homeassistant.config_entries import ConfigEntry
+from homeassistant.exceptions import HomeAssistantError
+from homeassistant.helpers.entity_platform import AddEntitiesCallback
+
+from .const import MAX_TOOL_ITERATIONS
+from .conversation import _async_langchain_stream, _chatlog_to_langchain, _ha_tool_to_dict
+
+LOGGER = logging.getLogger(__name__)
+
+
+async def async_setup_entry(
+ hass,
+ config_entry: ConfigEntry,
+ async_add_entities: AddEntitiesCallback,
+) -> None:
+ """Set up AI Task entity."""
+ async_add_entities([SmartChainAITaskEntity(config_entry)])
+
+
+class SmartChainAITaskEntity(ai_task.AITaskEntity):
+ """SmartChain AI Task entity for data generation."""
+
+ _attr_has_entity_name = True
+ _attr_name = None
+
+ def __init__(self, entry: ConfigEntry) -> None:
+ """Initialize the entity."""
+ self.entry = entry
+ self._attr_unique_id = f"{entry.entry_id}_ai_task"
+ self._attr_supported_features = ai_task.AITaskEntityFeature.GENERATE_DATA
+
+ async def _async_generate_data(
+ self,
+ task: ai_task.GenDataTask,
+ chat_log: conversation.ChatLog,
+ ) -> ai_task.GenDataTaskResult:
+ """Handle a generate data task."""
+ client = self.entry.runtime_data
+ tools: list[dict[str, Any]] = (
+ [_ha_tool_to_dict(tool) for tool in chat_log.llm_api.tools]
+ if chat_log.llm_api
+ else []
+ )
+ bound_client = client.bind_tools(tools) if tools else client
+
+ for _iteration in range(MAX_TOOL_ITERATIONS):
+ messages = _chatlog_to_langchain(chat_log)
+
+ try:
+ async for _content in chat_log.async_add_delta_content_stream(
+ self.entity_id,
+ _async_langchain_stream(bound_client, messages),
+ ):
+ pass
+ except Exception as err:
+ LOGGER.exception("AI Task error: %s", type(err))
+ raise HomeAssistantError(f"AI Task error: {err}") from err
+
+ if not chat_log.unresponded_tool_results:
+ break
+
+ if not isinstance(chat_log.content[-1], conversation.AssistantContent):
+ raise HomeAssistantError(
+ "Last content in chat log is not an AssistantContent"
+ )
+
+ text = chat_log.content[-1].content or ""
+
+ if task.structure:
+ from homeassistant.util.json import json_loads
+ from json import JSONDecodeError
+
+ try:
+ data = json_loads(text)
+ except JSONDecodeError as err:
+ LOGGER.error("Failed to parse structured response: %s", err)
+ raise HomeAssistantError(
+ "Failed to parse structured AI Task response"
+ ) from err
+
+ return ai_task.GenDataTaskResult(
+ conversation_id=chat_log.conversation_id,
+ data=data,
+ )
+
+ return ai_task.GenDataTaskResult(
+ conversation_id=chat_log.conversation_id,
+ data=text,
+ )
diff --git a/custom_components/gigachain/client_util.py b/custom_components/smartchain/client_util.py
similarity index 100%
rename from custom_components/gigachain/client_util.py
rename to custom_components/smartchain/client_util.py
diff --git a/custom_components/gigachain/config_flow.py b/custom_components/smartchain/config_flow.py
similarity index 87%
rename from custom_components/gigachain/config_flow.py
rename to custom_components/smartchain/config_flow.py
index b47d1ae..93a2df5 100644
--- a/custom_components/gigachain/config_flow.py
+++ b/custom_components/smartchain/config_flow.py
@@ -1,4 +1,4 @@
-"""Config flow for GigaChain integration."""
+"""Config flow for SmartChain integration."""
from __future__ import annotations
@@ -18,12 +18,14 @@
TemplateSelector)
from httpx import ConnectError
+from homeassistant.helpers import llm
+
from .client_util import validate_client
from .const import (CONF_API_KEY, CONF_CHAT_MODEL, CONF_CHAT_MODEL_USER,
CONF_ENGINE, CONF_ENGINE_OPTIONS, CONF_FOLDER_ID,
- CONF_MAX_TOKENS, CONF_PROFANITY, CONF_PROMPT,
- CONF_SKIP_VALIDATION, CONF_TEMPERATURE, CONF_VERIFY_SSL,
- DEFAULT_CHAT_MODEL, DEFAULT_VERIFY_SSL,
+ CONF_LLM_HASS_API, CONF_MAX_TOKENS, CONF_PROFANITY,
+ CONF_PROMPT, CONF_SKIP_VALIDATION, CONF_TEMPERATURE,
+ CONF_VERIFY_SSL, DEFAULT_CHAT_MODEL, DEFAULT_VERIFY_SSL,
ENGINE_MODELS, DEFAULT_PROFANITY, DEFAULT_PROMPT,
DEFAULT_SKIP_VALIDATION, DEFAULT_TEMPERATURE, DOMAIN,
ID_GIGACHAT, ID_OPENAI, ID_YANDEX_GPT, UNIQUE_ID,
@@ -75,7 +77,7 @@
class ConfigFlow(config_entries.ConfigFlow, domain=DOMAIN):
- """Handle a config flow for GigaChain."""
+ """Handle a config flow for SmartChain."""
VERSION = 1
@@ -146,7 +148,7 @@ def async_get_options_flow(
class OptionsFlow(config_entries.OptionsFlow):
- """GigaChain config flow options handler."""
+ """SmartChain config flow options handler."""
def __init__(self, config_entry: config_entries.ConfigEntry) -> None:
"""Initialize options flow."""
@@ -158,7 +160,7 @@ async def async_step_init(
"""Manage the options."""
unique_id = self.config_entry.unique_id
schema = common_config_option_schema(
- unique_id, self.config_entry.options
+ self.hass, unique_id, self.config_entry.options
)
if user_input is not None:
model = user_input.get(CONF_CHAT_MODEL_USER)
@@ -170,6 +172,10 @@ async def async_step_init(
errors={"base": "model_required"},
)
+ # Remove empty LLM API selection
+ if not user_input.get(CONF_LLM_HASS_API):
+ user_input.pop(CONF_LLM_HASS_API, None)
+
return self.async_create_entry(title=unique_id, data=user_input)
return self.async_show_form(
@@ -179,11 +185,17 @@ async def async_step_init(
def common_config_option_schema(
- unique_id: str, options: MappingProxyType[str, Any]
+ hass, unique_id: str, options: MappingProxyType[str, Any]
) -> vol.Schema:
- """Return a schema for GigaChain completion options."""
+ """Return a schema for SmartChain completion options."""
if not options:
options = DEFAULT_OPTIONS
+
+ hass_apis: list[selector.SelectOptionDict] = [
+ selector.SelectOptionDict(value=api.id, label=api.name)
+ for api in llm.async_get_apis(hass)
+ ]
+
schema = vol.Schema({
vol.Optional(
CONF_CHAT_MODEL,
@@ -200,9 +212,16 @@ def common_config_option_schema(
"suggested_value": options.get(CONF_CHAT_MODEL_USER)
},
): str,
+ vol.Optional(
+ CONF_LLM_HASS_API,
+ ): selector.SelectSelector(
+ selector.SelectSelectorConfig(
+ options=hass_apis, multiple=True, mode=SelectSelectorMode("dropdown")
+ ),
+ ),
vol.Optional(
CONF_PROMPT,
- description={"suggested_value": options[CONF_PROMPT]},
+ description={"suggested_value": options.get(CONF_PROMPT, DEFAULT_PROMPT)},
default=DEFAULT_PROMPT,
): TemplateSelector(),
vol.Optional(
diff --git a/custom_components/gigachain/const.py b/custom_components/smartchain/const.py
similarity index 66%
rename from custom_components/gigachain/const.py
rename to custom_components/smartchain/const.py
index 3328385..3ab1be7 100644
--- a/custom_components/gigachain/const.py
+++ b/custom_components/smartchain/const.py
@@ -1,8 +1,8 @@
-"""Constants for the GigaChain integration."""
+"""Constants for the SmartChain integration."""
from homeassistant.helpers import selector
-DOMAIN = "gigachain"
+DOMAIN = "smartchain"
CONF_ENGINE = "engine"
CONF_CHAT_MODEL = "model"
CONF_CHAT_MODEL_USER = "model_user"
@@ -21,9 +21,12 @@
CONF_CHAT_HISTORY = "chat_history"
DEFAULT_CHAT_HISTORY = True
CONF_PROMPT = "prompt"
-DEFAULT_PROMPT = """Ты HAL 9000, компьютер из цикла произведений «Космическая одиссея» Артура Кларка, обладающий способностью к самообучению.
-Мы находимся в умном доме под управлением системы Home Assistant.
-В доме есть следующие помещения и устройства:
+DEFAULT_PROMPT = """You are a smart home voice assistant {{ ha_name }} powered by Home Assistant.
+Answer truthfully and to the point. Answer in plain text, briefly and clearly.
+Answer in the user's language."""
+
+DEFAULT_DEVICES_PROMPT = """
+The following rooms, devices and sensors are available in the home:
{%- for area in areas() %}
{%- set area_info = namespace(printed=false) %}
{%- for device in area_devices(area) -%}
@@ -34,11 +37,20 @@
{%- set area_info.printed = true %}
{%- endif %}
- {{ device_attr(device, "name") }}{% if device_attr(device, "model") and (device_attr(device, "model") | string) not in (device_attr(device, "name") | string) %} ({{ device_attr(device, "model") }}){% endif %}
+
+ {%- for entity_id in device_entities(device) %}
+ {%- set entity_domain = entity_id.split('.')[0] %}
+ {%- set dc = state_attr(entity_id, 'device_class') %}
+ {%- set friendly = state_attr(entity_id, 'friendly_name') %}
+ {%- set entity_state = states(entity_id) %}
+ {%- if entity_state and entity_state != 'unavailable' %}
+ - {{ entity_id }} ({{ entity_domain }}{% if dc %}, {{ dc }}{% endif %}): {{ entity_state }}{% if state_attr(entity_id, 'unit_of_measurement') %} {{ state_attr(entity_id, 'unit_of_measurement') }}{% endif %}
+
+ {%- endif %}
+ {%- endfor %}
{%- endif %}
{%- endfor %}
-{%- endfor %}
-Когда отвечаешь, обращайся к собеседнику по имени Дэйв.
-"""
+{%- endfor %}"""
ID_GIGACHAT = "gigachat"
ID_YANDEX_GPT = "yandexgpt"
@@ -69,14 +81,14 @@
DEFAULT_MODELS_YANDEX_GPT = ["", "YandexGPT", "YandexGPT Lite", "Summary"]
MODELS_OPENAI = [
"",
+ "gpt-4.1",
+ "gpt-4.1-mini",
+ "gpt-4.1-nano",
"gpt-4o",
"gpt-4o-mini",
- "gpt-4-turbo",
- "gpt-4",
- "gpt-3.5-turbo",
- "o1",
- "o1-mini",
+ "o3",
"o3-mini",
+ "o4-mini",
]
ENGINE_MODELS = {
UNIQUE_ID_GIGACHAT: MODELS_GIGACHAT,
@@ -85,9 +97,12 @@
}
DEFAULT_MODEL = {
ID_GIGACHAT: None,
- ID_OPENAI: "gpt-4o-mini",
+ ID_OPENAI: "gpt-4.1-mini",
ID_YANDEX_GPT: None,
}
+CONF_LLM_HASS_API = "llm_hass_api"
CONF_API_KEY = "api_key"
CONF_FOLDER_ID = "folder_id"
+
+MAX_TOOL_ITERATIONS = 10
diff --git a/custom_components/smartchain/conversation.py b/custom_components/smartchain/conversation.py
new file mode 100644
index 0000000..c234fcd
--- /dev/null
+++ b/custom_components/smartchain/conversation.py
@@ -0,0 +1,239 @@
+"""Conversation entity for SmartChain integration."""
+
+import json
+import logging
+from collections.abc import AsyncIterable
+from typing import Any, Literal
+
+import voluptuous_openapi
+from home_assistant_intents import get_languages
+from homeassistant.components import conversation
+from homeassistant.components.conversation import (
+ ChatLog,
+ ConversationEntity,
+ ConversationInput,
+ ConversationResult,
+)
+from homeassistant.components.conversation.chat_log import (
+ AssistantContent,
+ SystemContent,
+ ToolResultContent,
+ UserContent,
+)
+from homeassistant.config_entries import ConfigEntry
+from homeassistant.helpers import intent, llm, template
+from homeassistant.helpers.entity_platform import AddEntitiesCallback
+from langchain_core.messages import (
+ AIMessage,
+ BaseMessage,
+ HumanMessage,
+ SystemMessage,
+ ToolMessage,
+)
+
+from .const import (
+ CONF_CHAT_HISTORY,
+ CONF_LLM_HASS_API,
+ CONF_PROCESS_BUILTIN_SENTENCES,
+ CONF_PROMPT,
+ DEFAULT_CHAT_HISTORY,
+ DEFAULT_DEVICES_PROMPT,
+ DEFAULT_PROCESS_BUILTIN_SENTENCES,
+ DEFAULT_PROMPT,
+ DOMAIN,
+ MAX_TOOL_ITERATIONS,
+)
+
+LOGGER = logging.getLogger(__name__)
+
+
+async def async_setup_entry(
+ hass,
+ config_entry: ConfigEntry,
+ async_add_entities: AddEntitiesCallback,
+) -> None:
+ """Set up conversation entity."""
+ async_add_entities([SmartChainConversationEntity(config_entry)])
+
+
+def _ha_tool_to_dict(tool: llm.Tool) -> dict[str, Any]:
+ """Convert HA llm.Tool to dict for LangChain bind_tools."""
+ parameters = voluptuous_openapi.convert(tool.parameters)
+ return {
+ "name": tool.name,
+ "description": tool.description or "",
+ "parameters": parameters,
+ }
+
+
+class SmartChainConversationEntity(ConversationEntity):
+ """SmartChain conversation entity using ConversationEntity API."""
+
+ _attr_has_entity_name = True
+ _attr_name = None
+ _attr_supports_streaming = True
+
+ def __init__(self, entry: ConfigEntry) -> None:
+ """Initialize the entity."""
+ self.entry = entry
+ self._attr_unique_id = entry.entry_id
+
+ @property
+ def supported_languages(self) -> list[str] | Literal["*"]:
+ """Return a list of supported languages."""
+ return get_languages()
+
+ async def _async_handle_message(
+ self,
+ user_input: ConversationInput,
+ chat_log: ChatLog,
+ ) -> ConversationResult:
+ """Handle a conversation message via ChatLog API."""
+ options = self.entry.options
+ llm_hass_api = options.get(CONF_LLM_HASS_API)
+ user_prompt = options.get(CONF_PROMPT, DEFAULT_PROMPT)
+
+ if llm_hass_api:
+ try:
+ await chat_log.async_provide_llm_data(
+ user_input.as_llm_context(DOMAIN),
+ llm_hass_api,
+ user_prompt,
+ user_input.extra_system_prompt,
+ )
+ except conversation.ConverseError as err:
+ return err.as_conversation_result()
+ else:
+ raw_prompt = user_prompt + DEFAULT_DEVICES_PROMPT
+ prompt = template.Template(raw_prompt, self.hass).async_render(
+ {"ha_name": self.hass.config.location_name},
+ parse_result=False,
+ )
+ chat_log.content[0] = SystemContent(content=prompt)
+
+ use_builtin = options.get(
+ CONF_PROCESS_BUILTIN_SENTENCES, DEFAULT_PROCESS_BUILTIN_SENTENCES
+ )
+ if use_builtin and not llm_hass_api:
+ from homeassistant.components.conversation import agent_manager
+
+ default_agent = agent_manager.async_get_agent(self.hass, None)
+ default_response = await default_agent.async_process(user_input)
+
+ if default_response.response.intent:
+ speech = (
+ default_response.response.speech.get("plain", {}).get("speech", "")
+ )
+ chat_log.async_add_assistant_content_without_tools(
+ AssistantContent(
+ agent_id=user_input.agent_id,
+ content=speech,
+ )
+ )
+ return default_response
+
+ client = self.entry.runtime_data
+ tools = (
+ [_ha_tool_to_dict(tool) for tool in chat_log.llm_api.tools]
+ if chat_log.llm_api
+ else []
+ )
+ bound_client = client.bind_tools(tools) if tools else client
+
+ for _iteration in range(MAX_TOOL_ITERATIONS):
+ chat_history_enabled = options.get(
+ CONF_CHAT_HISTORY, DEFAULT_CHAT_HISTORY
+ )
+ if chat_history_enabled:
+ messages = _chatlog_to_langchain(chat_log)
+ else:
+ messages = [
+ SystemMessage(content=chat_log.content[0].content),
+ HumanMessage(content=user_input.text),
+ ]
+
+ try:
+ async for _content in chat_log.async_add_delta_content_stream(
+ user_input.agent_id,
+ _async_langchain_stream(bound_client, messages),
+ ):
+ pass
+ except Exception as err:
+ LOGGER.exception("Unexpected exception %s", type(err))
+ response = intent.IntentResponse(language=user_input.language)
+ response.async_set_error(
+ intent.IntentResponseErrorCode.UNKNOWN,
+ f"Houston we have a problem: {err}",
+ )
+ return ConversationResult(
+ conversation_id=chat_log.conversation_id, response=response
+ )
+
+ if not chat_log.unresponded_tool_results:
+ break
+
+ return conversation.async_get_result_from_chat_log(user_input, chat_log)
+
+
+def _chatlog_to_langchain(chat_log: ChatLog) -> list[BaseMessage]:
+ """Convert ChatLog content to LangChain message list."""
+ messages: list[BaseMessage] = []
+ for content in chat_log.content:
+ if isinstance(content, SystemContent):
+ messages.append(SystemMessage(content=content.content))
+ elif isinstance(content, UserContent):
+ messages.append(HumanMessage(content=content.content))
+ elif isinstance(content, AssistantContent):
+ if content.tool_calls:
+ tool_calls = [
+ {
+ "id": tc.id,
+ "name": tc.tool_name,
+ "args": tc.tool_args,
+ }
+ for tc in content.tool_calls
+ ]
+ messages.append(
+ AIMessage(
+ content=content.content or "",
+ tool_calls=tool_calls,
+ )
+ )
+ elif content.content:
+ messages.append(AIMessage(content=content.content))
+ elif isinstance(content, ToolResultContent):
+ messages.append(
+ ToolMessage(
+ content=json.dumps(content.tool_result),
+ tool_call_id=content.tool_call_id,
+ name=content.tool_name,
+ )
+ )
+ return messages
+
+
+async def _async_langchain_stream(
+ client: Any, messages: list[BaseMessage]
+) -> AsyncIterable[dict[str, Any]]:
+ """Convert LangChain astream chunks to HA delta dicts."""
+ first = True
+ async for chunk in client.astream(messages):
+ delta: dict[str, Any] = {}
+ if first:
+ delta["role"] = "assistant"
+ first = False
+ if chunk.content:
+ delta["content"] = chunk.content
+
+ if chunk.tool_calls:
+ delta["tool_calls"] = [
+ llm.ToolInput(
+ tool_name=tc["name"],
+ tool_args=tc["args"],
+ id=tc["id"],
+ )
+ for tc in chunk.tool_calls
+ ]
+
+ if delta:
+ yield delta
diff --git a/custom_components/gigachain/manifest.json b/custom_components/smartchain/manifest.json
similarity index 63%
rename from custom_components/gigachain/manifest.json
rename to custom_components/smartchain/manifest.json
index 540523d..e56c4da 100644
--- a/custom_components/gigachain/manifest.json
+++ b/custom_components/smartchain/manifest.json
@@ -1,14 +1,14 @@
{
- "domain": "gigachain",
- "name": "GigaChain",
+ "domain": "smartchain",
+ "name": "SmartChain",
"codeowners": ["@gritaro"],
"config_flow": true,
"dependencies": ["conversation"],
- "documentation": "https://github.com/gritaro/gigachain",
+ "documentation": "https://github.com/gritaro/ha-smartchain",
"homekit": {},
"integration_type": "service",
"iot_class": "cloud_polling",
- "issue_tracker": "https://github.com/gritaro/gigachain/issues",
+ "issue_tracker": "https://github.com/gritaro/ha-smartchain/issues",
"requirements": [
"home-assistant-intents",
"langchain-gigachat>=0.3.0",
@@ -16,5 +16,5 @@
"langchain-community>=0.4.0",
"yandexcloud==0.295.0"
],
- "version": "0.5.0"
+ "version": "0.7.0"
}
diff --git a/custom_components/gigachain/strings.json b/custom_components/smartchain/strings.json
similarity index 92%
rename from custom_components/gigachain/strings.json
rename to custom_components/smartchain/strings.json
index e6d3296..1fe8687 100644
--- a/custom_components/gigachain/strings.json
+++ b/custom_components/smartchain/strings.json
@@ -2,7 +2,7 @@
"config": {
"step": {
"user": {
- "title": "GigaChain configuration - select engine",
+ "title": "SmartChain configuration - select engine",
"data": {
"engine": "LLM Engine"
}
@@ -47,6 +47,7 @@
"init": {
"title": "Model configuration",
"data": {
+ "llm_hass_api": "Assist API (Control HA devices)",
"prompt": "Prompt Template",
"model": "Completion Model",
"model_user": "Custom Model Name (leave empty to use from list above)",
diff --git a/custom_components/gigachain/translations/en.json b/custom_components/smartchain/translations/en.json
similarity index 92%
rename from custom_components/gigachain/translations/en.json
rename to custom_components/smartchain/translations/en.json
index e6d3296..1fe8687 100644
--- a/custom_components/gigachain/translations/en.json
+++ b/custom_components/smartchain/translations/en.json
@@ -2,7 +2,7 @@
"config": {
"step": {
"user": {
- "title": "GigaChain configuration - select engine",
+ "title": "SmartChain configuration - select engine",
"data": {
"engine": "LLM Engine"
}
@@ -47,6 +47,7 @@
"init": {
"title": "Model configuration",
"data": {
+ "llm_hass_api": "Assist API (Control HA devices)",
"prompt": "Prompt Template",
"model": "Completion Model",
"model_user": "Custom Model Name (leave empty to use from list above)",
diff --git a/custom_components/gigachain/translations/ru.json b/custom_components/smartchain/translations/ru.json
similarity index 71%
rename from custom_components/gigachain/translations/ru.json
rename to custom_components/smartchain/translations/ru.json
index 68f3113..5ceae8d 100644
--- a/custom_components/gigachain/translations/ru.json
+++ b/custom_components/smartchain/translations/ru.json
@@ -2,20 +2,20 @@
"config": {
"step": {
"user": {
- "title": "GigaChain конфигурация - выбор LLM",
+ "title": "SmartChain - выбор LLM провайдера",
"data": {
- "engine": "Большая языковая модель"
+ "engine": "LLM провайдер"
}
},
"gigachat": {
- "title": "Конфигурация GigaChat",
+ "title": "GigaChat",
"data": {
"api_key": "Авторизационные данные",
"skip_validation": "Пропустить проверку"
}
},
"yandexgpt": {
- "title": "Конфигурация YandexGPT",
+ "title": "YandexGPT",
"data": {
"api_key": "API ключ",
"folder_id": "Идентификатор каталога (Folder ID)",
@@ -23,7 +23,7 @@
}
},
"openai": {
- "title": "Конфигурация OpenAI",
+ "title": "OpenAI",
"data": {
"api_key": "API ключ",
"skip_validation": "Пропустить проверку"
@@ -31,7 +31,7 @@
}
},
"abort": {
- "already_configured": "Эта модель уже настроена"
+ "already_configured": "Этот провайдер уже настроен"
},
"error": {
"cannot_connect": "Не удаётся подключиться",
@@ -45,16 +45,17 @@
},
"step": {
"init": {
- "title": "Конфигурация модели",
+ "title": "Настройки модели",
"data": {
+ "llm_hass_api": "Assist API (управление устройствами HA)",
"prompt": "Системный промпт",
"model": "Модель",
- "model_user": "Своё имя модели (оставьте пустым для использования имени из списка)",
+ "model_user": "Своё имя модели (оставьте пустым для использования из списка)",
"temperature": "Температура",
"max_tokens": "Максимум токенов",
"profanity": "Цензура",
"verify_ssl": "Проверка SSL сертификатов",
- "process_builtin_sentences": "Использовать встроенный HA командный процессор",
+ "process_builtin_sentences": "Встроенный командный процессор HA",
"chat_history": "История сообщений"
}
}
diff --git a/docs/COMPETITIVE_ANALYSIS.md b/docs/COMPETITIVE_ANALYSIS.md
new file mode 100644
index 0000000..5226c60
--- /dev/null
+++ b/docs/COMPETITIVE_ANALYSIS.md
@@ -0,0 +1,382 @@
+# GigaChain — Конкурентный анализ и точки роста
+
+Дата: 2026-03-10 | Версия: 0.5.0
+
+## Оглавление
+
+1. [Конкуренты — интеграции HA для LLM](#1-конкуренты--интеграции-ha-для-llm)
+2. [Что есть у конкурентов, чего нет у нас](#2-что-есть-у-конкурентов-чего-нет-у-нас)
+3. [Российские и китайские модели](#3-российские-и-китайские-модели--кого-можно-подключить)
+4. [Легковесные локальные модели](#4-легковесные-локальные-модели)
+5. [Точки роста и пути развития](#5-точки-роста-и-пути-развития)
+6. [Стратегическое позиционирование](#6-стратегическое-позиционирование)
+7. [Источники](#7-источники)
+
+---
+
+## 1. Конкуренты — интеграции HA для LLM
+
+### Официальные интеграции (встроены в HA core)
+
+| Интеграция | Провайдер | Device Control | AI Task | Streaming | Vision | MCP |
+|---|---|---|---|---|---|---|
+| OpenAI Conversation | OpenAI | Assist API | да | да | да | да |
+| Anthropic | Claude | Assist API | да | да | нет | да |
+| Google Gemini | Gemini | Assist API | да | да | да | да |
+| Ollama | Локальные | Assist API | да | да | нет | да |
+| OpenRouter | 400+ моделей | Assist API | да | да | нет | да |
+
+Все официальные интеграции поддерживают:
+- Assist API для управления устройствами
+- AI Task entity для генерации данных в автоматизациях
+- Sub-entries (несколько агентов с разными моделями через одну интеграцию)
+- MCP (Model Context Protocol) для расширения возможностей внешними инструментами
+- Streaming ответов
+- Conversational follow-ups (LLM может задавать уточняющие вопросы)
+- Per-device LLM assignment (разный LLM для разных устройств)
+
+### Custom-интеграции (HACS)
+
+#### Extended OpenAI Conversation (~1.5k stars)
+- GitHub: https://github.com/jekalmin/extended_openai_conversation
+- **Function calling** — вызов сервисов HA через OpenAI API
+- **Создание автоматизаций** через естественный язык
+- **Чтение истории состояний** — LLM знает, что было раньше
+- **REST API** — запросы к внешним API
+- **Веб-скрейпинг** — получение данных с веб-страниц
+- **Skill-система** — загружаемые навыки из директории
+- **Multi-agent** — Dispatcher Agent маршрутизирует запросы между специализированными агентами
+- **Attach Username** — персонализация по имени пользователя
+- Поддержка native functions: `execute_service`, `add_automation`, `get_history`
+
+#### YandexGPT (black-roland, 38 stars)
+- GitHub: https://github.com/black-roland/homeassistant-yandexgpt
+- **Управление устройствами** — включение/выключение света, регулировка температуры, запуск скриптов
+- **YandexART** — генерация изображений
+- **Telegram-бот** — использование как backend для Telegram
+- **Yandex SpeechKit** — companion-интеграция для STT/TTS
+- Последний релиз: v1.5.5 (декабрь 2025)
+- Лицензия: MPL-2.0
+
+#### Cloud.ru Foundation Models (black-roland, новый)
+- GitHub: https://github.com/black-roland/homeassistant-cloud-ru-ai
+- **Открытые модели**: GPT-OSS-120b, Qwen3, Llama, DeepSeek R1 Distill, GLM-4.5, T-Pro
+- **Управление устройствами** — полный контроль через чат
+- Основан на официальной интеграции OpenAI HA
+- Лицензия: Apache 2.0
+
+#### Home-LLM (acon96, ~3k stars)
+- GitHub: https://github.com/acon96/home-llm
+- **Полностью локальный** — никаких облачных сервисов
+- **Fine-tuned модели** — Home-3B-v3 (97% точность function calling), Home-1B-v3
+- **Tool calling** — переписан для поддержки agentic tool use loop
+- **AI Task entity** — генерация данных для автоматизаций
+- **Multi-language** — EN, DE, FR, ES, PL
+- **CPU-friendly** — работает на Raspberry Pi
+- Backends: Ollama, llama.cpp, OpenAI-compatible API
+
+#### LLM Vision (~1.5k stars)
+- GitHub: https://github.com/valentinfrlch/ha-llmvision
+- **Мультимодальный** — анализ изображений, видео, live камер, Frigate events
+- **Timeline** — хранит историю событий камер
+- **Распознавание** — люди, номерные знаки, объекты
+- **Голосовые запросы** — "Была ли активность во дворе вчера?"
+- Провайдеры: OpenAI, Anthropic, Gemini, Ollama, OpenRouter, и др.
+
+#### GigaChain (наш, 15 stars)
+- GigaChat + YandexGPT + OpenAI через LangChain
+- Streaming ответов
+- ChatLog для истории
+- Builtin sentence processor
+- Системный промпт с Jinja2
+
+---
+
+## 2. Что есть у конкурентов, чего нет у нас
+
+### Критические отставания
+
+| Фича | У кого есть | Описание |
+|---|---|---|
+| Управление устройствами (Assist API) | Все official, Extended OpenAI, YandexGPT, Cloud.ru | LLM может включать свет, менять температуру, запускать сценарии |
+| AI Task entity | Все official, Home-LLM | Генерация данных для автоматизаций через `ai_task.generate_data` |
+| MCP (Model Context Protocol) | Все official | Расширение возможностей агента внешними инструментами |
+| Function calling / вызов сервисов | Extended OpenAI, все official | LLM вызывает произвольные сервисы HA |
+| Vision / мультимодальность | OpenAI, Gemini, LLM Vision | Анализ камер и изображений |
+| Генерация изображений | YandexGPT (YandexART) | Создание изображений по описанию |
+| Создание автоматизаций через AI | Extended OpenAI | Генерация автоматизаций HA из естественного языка |
+| Доступ к истории состояний | Extended OpenAI | LLM анализирует тренды и прошлые события |
+
+### Менее критичные
+
+| Фича | У кого есть |
+|---|---|
+| Multi-agent (Dispatcher + специализированные) | Extended OpenAI |
+| Skill-система (загружаемые навыки) | Extended OpenAI |
+| Telegram-бот | YandexGPT |
+| STT/TTS от того же провайдера | YandexGPT + SpeechKit |
+| Prompt caching | llama.cpp custom-conversation |
+| Sub-entries (несколько агентов) | Все official (HA 2025.8+) |
+| Conversational follow-ups | Все official |
+| Per-device LLM assignment | Все official |
+
+---
+
+## 3. Российские и китайские модели — кого можно подключить
+
+### Российские модели с API
+
+#### GigaChat 2.0 (Сбер) — уже подключён
+- Линейка: Lite / Pro / MAX
+- Контекст: до 128K токенов
+- Мультимодальность: да (GigaChat 2.0)
+- Генерация изображений: да (Kandinsky)
+- Цена: ~650 руб/1M токенов (MAX), 1M бесплатных токенов/месяц для разработчиков
+- LangChain: `langchain-gigachat` (подключён)
+- Function calling: поддерживается
+
+#### YandexGPT 4 / Alice AI LLM (Яндекс) — уже подключён
+- Линейка: Lite / Pro
+- Контекст: до 32K токенов (до 60 страниц)
+- Цена: ~1220 руб/1M токенов (Pro)
+- LangChain: `langchain_community.chat_models.ChatYandexGPT` (подключён)
+- Доп. сервисы: YandexART (генерация изображений), SpeechKit (STT/TTS)
+- Примечание: в октябре 2025 переименован в Alice AI LLM
+
+#### T-Pro 2.0 (Т-Банк / Т-Технологии) — НЕ подключён
+- Параметры: 32B
+- Лицензия: Apache 2.0 (полностью открытая)
+- Гибридный reasoning (быстрые ответы + многошаговое рассуждение)
+- На 30% экономичнее Qwen3 и DeepSeek R1-Distil на русском
+- Лидер бенчмарков MERA, ruMMLU, ruArena Hard для русского
+- Основана на Qwen3 32B с улучшенным кириллическим токенизатором
+- Доступ: HuggingFace, self-hosted через Ollama/vLLM
+- **Рекомендация: подключить через Ollama backend**
+
+#### T-Lite (Т-Банк) — НЕ подключён
+- Параметры: 7B
+- Лицензия: Apache 2.0
+- Компактная модель для устройств со средней производительностью
+- Доступ: HuggingFace, Ollama
+- **Рекомендация: подключить через Ollama как легковесную опцию**
+
+#### Cotype Pro 2.5 (MTS AI / MWS AI) — НЕ подключён
+- Лидер среди российских LLM в бенчмарке MERA
+- Агентные навыки: в 10 раз эффективнее Cotype Pro 2
+- Превосходит Qwen3-32B на 22% по точности на русском
+- Доступ: enterprise API (MWS Cloud)
+- **Рекомендация: рассмотреть при наличии API**
+
+#### Cotype Nano (MTS AI) — НЕ подключён
+- Открытая модель, работает на мобильных устройствах и ноутбуках
+- Лучшие результаты в своём классе на Ru Arena Hard
+- **Рекомендация: подключить через Ollama**
+
+### Китайские модели (доступны из России)
+
+#### DeepSeek V3 / R1 — НЕ подключён
+- V3: general-purpose, tool calling, structured output
+- R1: reasoning, chain-of-thought
+- LangChain: `langchain-deepseek` (`ChatDeepSeek`)
+- Цена: самая низкая на рынке (~$0.14/1M input tokens)
+- Доступ из РФ: API (возможны проблемы с блокировкой IP Роскомнадзором), self-hosted через Ollama
+- **Рекомендация: подключить как самый дешёвый cloud-провайдер**
+
+#### Qwen 3 (Alibaba) — НЕ подключён
+- Модели от 0.6B до 235B параметров
+- Самая скачиваемая серия моделей на HuggingFace (2025-2026)
+- Reasoning mode, tool calling
+- LangChain: `ChatOllama` или Cloud.ru
+- **Рекомендация: подключить через Ollama backend**
+
+#### GLM-4.5 (Zhipu AI) — НЕ подключён
+- Доступ: Cloud.ru Foundation Models
+- **Рекомендация: подключить через Cloud.ru или Ollama**
+
+#### Baichuan, Yi, MiniCPM — НЕ подключены
+- Open-source, self-hosted через Ollama
+- **Рекомендация: автоматически доступны при поддержке Ollama**
+
+---
+
+## 4. Легковесные локальные модели
+
+Для пользователей без мощного GPU или с Raspberry Pi:
+
+| Модель | Параметры | RAM | Язык | Особенности |
+|---|---|---|---|---|
+| Home-3B-v3 | 3B | ~2GB | EN/DE/FR/ES | 97% точность function calling HA |
+| Home-1B-v3 | 1B | ~1GB | EN | Raspberry Pi compatible |
+| T-Lite | 7B | ~4GB | RU | лучшая для русского в классе 7B |
+| T-Pro 2.0 | 32B | ~18GB | RU | лидер русскоязычных бенчмарков |
+| Qwen3 | 0.6B-4B | 0.5-3GB | RU/EN/ZH | reasoning, tool calling |
+| Phi-4-mini | 3.8B | ~2GB | EN | Microsoft, компактная |
+| Gemma 3 | 1B-4B | 1-3GB | EN | Google, vision support |
+| DeepSeek R1 Distill | 1.5B-14B | 1-8GB | EN/ZH | reasoning |
+| Cotype Nano | small | ~2GB | RU | MTS AI, открытая |
+| MiniCPM | 1.2B-8B | 1-4GB | ZH/EN | OpenBMB, компактная |
+
+Все локальные модели доступны через **Ollama** — единый backend для self-hosted LLM.
+
+---
+
+## 5. Точки роста и пути развития
+
+### Приоритет: Высокий (конкурентный паритет)
+
+#### 5.1 Управление устройствами через Assist API
+- **Что:** Использовать `chat_log.async_provide_llm_data()` для доступа к HA tools
+- **Зачем:** Главная фича, которую имеют ВСЕ конкуренты. Без неё GigaChain — только чат-бот, не smart home agent
+- **Как:** HA LLM API предоставляет intents для управления exposed entities. Нужно передать tools в LLM и обработать tool calls
+- **Сложность:** Средняя. GigaChat и DeepSeek поддерживают function calling. Паттерн задокументирован в HA developer docs
+
+#### 5.2 AI Task entity
+- **Что:** Добавить `AITaskEntity` с методом `_async_generate_data()`
+- **Зачем:** Позволит использовать GigaChain в автоматизациях, скриптах, шаблонах через `ai_task.generate_data`
+- **Как:** Новый entity наряду с ConversationEntity, может разделять общую логику обработки chat_log
+- **Сложность:** Низкая-средняя
+
+#### 5.3 Новые провайдеры LLM
+- **DeepSeek** (`pip install langchain-deepseek`) — `ChatDeepSeek`, самый дешёвый, tool calling
+- **Ollama** (`pip install langchain-ollama`) — `ChatOllama`, все локальные модели (T-Pro, Qwen, Llama, DeepSeek)
+- **Anthropic** (`pip install langchain-anthropic`) — `ChatAnthropic`, extended thinking
+- **Зачем:** Расширение аудитории, поддержка локальных моделей, снижение стоимости
+- **Сложность:** Низкая — архитектура через LangChain уже позволяет добавлять провайдеров в `client_util.py`
+
+### Приоритет: Средний (дифференциация)
+
+#### 5.4 Function calling / вызов сервисов HA
+- **Что:** LLM вызывает произвольные сервисы HA (свет, климат, сценарии)
+- **Зачем:** Extended OpenAI Conversation — самая популярная custom-интеграция именно из-за этой фичи
+- **Как:** Определить tool specs для `execute_service`, `get_history`, передавать в LLM, обрабатывать tool calls в цикле
+- **Сложность:** Средняя-высокая
+
+#### 5.5 Vision / мультимодальность
+- **Что:** Анализ изображений с камер через LLM
+- **Зачем:** GigaChat 2.0 поддерживает мультимодальность. Можно анализировать камеры без LLM Vision
+- **Как:** Передавать изображения как attachments в LLM запрос
+- **Сложность:** Средняя
+
+#### 5.6 Генерация изображений
+- **Что:** GigaChat (Kandinsky) и YandexART для создания изображений
+- **Зачем:** Уникальная фича для российского рынка. У конкурента YandexGPT уже есть
+- **Как:** Отдельный сервис или entity для генерации
+- **Сложность:** Средняя
+
+#### 5.7 Sub-entries (несколько агентов)
+- **Что:** Позволить создавать несколько conversation agents с разными моделями/промптами через одну интеграцию
+- **Зачем:** Паттерн из HA 2025.8+. Один агент для чата, другой для device control, третий для генерации
+- **Сложность:** Средняя
+
+#### 5.8 MCP (Model Context Protocol)
+- **Что:** Интеграция с MCP серверами для расширения возможностей агента
+- **Зачем:** Все official-интеграции поддерживают. Даёт доступ к новостям, todo-спискам, внешним данным
+- **Сложность:** Средняя-высокая
+
+### Приоритет: Низкий (nice to have)
+
+#### 5.9 Доступ к истории состояний
+- LLM анализирует тренды и прошлые события ("Какая была температура вчера?")
+
+#### 5.10 Telegram-бот
+- Использовать GigaChain как backend для Telegram (как у YandexGPT)
+
+#### 5.11 STT/TTS интеграция
+- Связка с Yandex SpeechKit или GigaChat TTS для полного voice pipeline на русском
+
+#### 5.12 Prompt caching
+- Кэширование промптов для ускорения повторных запросов (как в llama.cpp)
+
+#### 5.13 Multi-agent
+- Dispatcher agent маршрутизирует запросы между специализированными агентами
+
+#### 5.14 Skill-система
+- Загружаемые "навыки" для разных доменов (погода, расписание, рецепты)
+
+#### 5.15 Conversational follow-ups
+- LLM задаёт уточняющие вопросы, HA слушает ответ
+
+---
+
+## 6. Стратегическое позиционирование
+
+### Текущее УТП (Unique Selling Proposition)
+
+GigaChain — **единственная** HA интеграция, объединяющая GigaChat + YandexGPT + OpenAI в одном компоненте через LangChain. Это позволяет:
+- Переключаться между провайдерами без переустановки
+- Использовать единый интерфейс для разных LLM
+- Легко добавлять новые модели через LangChain экосистему
+
+### Слабые стороны
+
+- Нет управления устройствами — главный разрыв с конкурентами
+- Нет AI Task — не может использоваться в автоматизациях
+- Нет локальных моделей (Ollama) — зависимость от cloud API
+- Небольшое сообщество (15 stars vs 3k у Home-LLM)
+
+### Рекомендуемая дорожная карта
+
+```mermaid
+gantt
+ title GigaChain Roadmap
+ dateFormat YYYY-MM
+ section Высокий приоритет
+ Assist API + Device Control :2026-03, 2026-04
+ AI Task entity :2026-04, 2026-05
+ DeepSeek + Ollama провайдеры :2026-04, 2026-05
+ section Средний приоритет
+ Function calling :2026-05, 2026-06
+ Vision / мультимодальность :2026-06, 2026-07
+ Sub-entries :2026-06, 2026-07
+ Генерация изображений :2026-07, 2026-08
+ section Низкий приоритет
+ Multi-agent :2026-08, 2026-09
+ Telegram-бот :2026-09, 2026-10
+```
+
+### Целевая аудитория
+
+1. **Российские пользователи HA** — GigaChat + YandexGPT без VPN
+2. **Privacy-conscious** — Ollama + T-Pro/Qwen для полностью локального решения
+3. **Мультипровайдерные** — один компонент вместо нескольких интеграций
+4. **Разработчики** — LangChain экосистема для кастомизации
+
+---
+
+## 7. Источники
+
+### Официальная документация HA
+- https://www.home-assistant.io/blog/2025/09/11/ai-in-home-assistant/
+- https://developers.home-assistant.io/docs/core/llm/
+- https://www.home-assistant.io/integrations/openai_conversation/
+- https://www.home-assistant.io/integrations/anthropic/
+- https://www.home-assistant.io/integrations/google_generative_ai_conversation/
+- https://www.home-assistant.io/integrations/ollama/
+- https://www.home-assistant.io/integrations/open_router/
+- https://www.home-assistant.io/integrations/ai_task/
+- https://www.home-assistant.io/blog/2025/08/06/release-20258/
+- https://developers.home-assistant.io/docs/core/entity/ai-task/
+- https://developers.home-assistant.io/docs/core/entity/conversation
+
+### Custom-интеграции
+- https://github.com/jekalmin/extended_openai_conversation
+- https://github.com/black-roland/homeassistant-yandexgpt
+- https://github.com/black-roland/homeassistant-cloud-ru-ai
+- https://github.com/acon96/home-llm
+- https://github.com/valentinfrlch/ha-llmvision
+
+### Российские LLM
+- https://vc.ru/ai/2733649-rossiyskie-neuroseti-2026-modeli-i-servisy-dlya-biznesa
+- https://habr.com/ru/companies/tbank/articles/928956/
+- https://mts.ai/tech/mts-ai-releases-cotype-pro-2-second-generation-business-focused-llm/
+- https://www.tbank.ru/about/news/11122024-the-t-technologies-group-has-introduced-the-worlds-most-efficient-open-large-language-models-in-russian/
+
+### Китайские LLM
+- https://intuitionlabs.ai/articles/chinese-open-source-llms-2025
+- https://changelog.langchain.com/announcements/deepseek-integration-in-langchain
+- https://www.index.dev/blog/chinese-ai-models-deepseek
+
+### LangChain интеграции
+- https://docs.langchain.com/oss/python/integrations/providers/yandex
+- https://docs.langchain.com/oss/python/integrations/chat/deepseek
+- https://ollama.com/fixt/home-3b-v3
diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md
new file mode 100644
index 0000000..d47e5a4
--- /dev/null
+++ b/docs/ROADMAP.md
@@ -0,0 +1,371 @@
+# GigaChain — Дорожная карта развития
+
+Дата: 2026-03-10 | Текущая версия: 0.6.0
+
+## Оглавление
+
+1. [Текущее состояние](#1-текущее-состояние)
+2. [Фаза 1 — Конкурентный паритет](#2-фаза-1--конкурентный-паритет-v07--v09)
+3. [Фаза 2 — Дифференциация](#3-фаза-2--дифференциация-v10--v13)
+4. [Фаза 3 — Лидерство](#4-фаза-3--лидерство-v14)
+5. [Технические детали по задачам](#5-технические-детали-по-задачам)
+
+---
+
+## 1. Текущее состояние
+
+### Реализовано (v0.1–v0.6)
+
+| Версия | Что сделано |
+|--------|-------------|
+| 0.1.x | Базовая интеграция: GigaChat + YandexGPT + OpenAI, Config/Options Flow, история диалогов, Jinja2 промпт |
+| 0.2.0 | Исправление блокировки event loop, deprecated API, утечки памяти, удаление Anyscale |
+| 0.2.1 | verify_ssl для GigaChat, обновление CI (Python 3.12, ruff) |
+| 0.3.0 | Миграция на `ConversationEntity` API, `conversation.py`, pytest (20 тестов) |
+| 0.4.0 | Миграция на ChatLog, langchain-gigachat/langchain-openai, CI pytest (26 тестов) |
+| 0.5.0 | Streaming ответов через `astream()` + `async_add_delta_content_stream()` (29 тестов) |
+| 0.6.0 | **Assist API** — управление устройствами через tool calling, LLM API selector, обновление промпта и моделей (34 теста) |
+
+### Текущая архитектура
+
+```mermaid
+graph TB
+ subgraph "GigaChain v0.6.0"
+ CF[Config Flow] --> CU[client_util.py]
+ CU --> GC[GigaChat]
+ CU --> YGP[YandexGPT]
+ CU --> OAI[OpenAI]
+
+ CE[ConversationEntity] --> CL[ChatLog]
+ CE --> ST[Streaming]
+ CE --> AA[Assist API]
+ AA --> TC[Tool Calling Loop]
+ TC --> BT[bind_tools]
+ end
+
+ subgraph "Home Assistant"
+ HA_LLM[HA LLM API] --> AA
+ HA_TOOLS[Intents & Services] --> HA_LLM
+ end
+```
+
+### Разрыв с конкурентами
+
+| Фича | Official HA | Extended OpenAI | YandexGPT | Home-LLM | GigaChain |
+|-------|:-----------:|:---------------:|:---------:|:--------:|:---------:|
+| Assist API / Device Control | + | + | + | + | **+ (v0.6)** |
+| AI Task entity | + | - | - | + | - |
+| Streaming | + | + | - | + | **+ (v0.5)** |
+| MCP | + | - | - | - | - |
+| Vision | + (OpenAI, Gemini) | - | - | - | - |
+| Генерация изображений | - | - | + | - | - |
+| Function calling (custom) | - | + | + | + | - |
+| Sub-entries | + | - | - | - | - |
+| Ollama / локальные модели | + | - | - | + | - |
+| Multi-agent | - | + | - | - | - |
+| Telegram-бот | - | - | + | - | - |
+| История состояний | - | + | - | - | - |
+
+---
+
+## 2. Фаза 1 — Конкурентный паритет (v0.7 – v0.9)
+
+Цель: закрыть критические разрывы с конкурентами, стать полноценным smart home agent.
+
+### v0.7 — AI Task entity
+
+**Приоритет:** Высокий
+**Сложность:** Низкая-средняя
+**Зависимости:** нет
+
+**Что:**
+- Добавить `AITaskEntity` с методом `_async_generate_data(task, chat_log)`
+- Позволяет использовать GigaChain в автоматизациях HA через `ai_task.generate_data`
+- Примеры: "Составь план уборки на основе загрязнённости комнат", "Проанализируй расход электричества за неделю"
+
+**Файлы:**
+- `custom_components/gigachain/ai_task.py` — новый файл с `GigaChainAITaskEntity`
+- `custom_components/gigachain/__init__.py` — добавить `Platform.AI_TASK`
+- `custom_components/gigachain/manifest.json` — добавить `"ai_task"` в dependencies
+- `tests/test_ai_task.py` — тесты
+
+**Реализация:**
+```python
+class GigaChainAITaskEntity(AITaskEntity):
+ async def _async_generate_data(
+ self, task: ai_task.GenData, chat_log: ChatLog
+ ) -> None:
+ # Предоставить LLM данные (tools, prompt)
+ await chat_log.async_provide_llm_data(...)
+ # Вызвать LLM через общую логику streaming + tool calling
+ # Результат записывается в chat_log автоматически
+```
+
+**Референсы:**
+- https://developers.home-assistant.io/docs/core/entity/ai-task/
+- `homeassistant.components.openai_conversation.ai_task`
+
+---
+
+### v0.8 — Новые провайдеры LLM (Ollama, DeepSeek, Anthropic)
+
+**Приоритет:** Высокий
+**Сложность:** Низкая
+**Зависимости:** нет
+
+**Что:**
+Добавить 3 новых провайдера через LangChain. Архитектура уже позволяет — нужно расширить `client_util.py` и Config Flow.
+
+#### 0.8.1 — Ollama (локальные модели)
+
+Открывает доступ ко всем локальным моделям: T-Pro 2.0, T-Lite, Qwen3, Llama, DeepSeek, Gemma, Phi, Home-3B.
+
+**Файлы:**
+- `const.py` — `ID_OLLAMA`, `UNIQUE_ID_OLLAMA`, модели, `CONF_BASE_URL`
+- `client_util.py` — `ChatOllama(model=..., base_url=...)`
+- `config_flow.py` — шаг `async_step_ollama` (base_url + model)
+- `manifest.json` — `langchain-ollama>=0.3.0`
+- `strings.json`, `translations/` — строки для Ollama
+
+**Config:**
+- `base_url` (по умолчанию `http://localhost:11434`)
+- `model` (текстовое поле, т.к. модели загружаются пользователем)
+
+#### 0.8.2 — DeepSeek
+
+Самый дешёвый cloud-провайдер. V3 для обычных задач, R1 для reasoning.
+
+**Файлы:**
+- `const.py` — `ID_DEEPSEEK`, модели (`deepseek-chat`, `deepseek-reasoner`)
+- `client_util.py` — `ChatDeepSeek(model=..., api_key=...)`
+- `config_flow.py` — шаг `async_step_deepseek`
+- `manifest.json` — `langchain-deepseek>=0.1.0`
+
+#### 0.8.3 — Anthropic (Claude)
+
+Для пользователей, которые хотят Claude через GigaChain.
+
+**Файлы:**
+- `const.py` — `ID_ANTHROPIC`, модели (`claude-sonnet-4-6`, `claude-haiku-4-5`)
+- `client_util.py` — `ChatAnthropic(model=..., api_key=...)`
+- `config_flow.py` — шаг `async_step_anthropic`
+- `manifest.json` — `langchain-anthropic>=0.3.0`
+
+---
+
+### v0.9 — Sub-entries (несколько агентов)
+
+**Приоритет:** Средний-высокий
+**Сложность:** Средняя
+**Зависимости:** v0.8 (больше пользы с несколькими провайдерами)
+
+**Что:**
+- Позволить создавать несколько conversation/AI task agents с разными моделями и промптами через одну интеграцию
+- Паттерн из HA 2025.8+ — все официальные интеграции перешли на sub-entries
+- Пример: "GigaChat Max для управления домом" + "GigaChat Lite для чата" + "DeepSeek R1 для аналитики"
+
+**Файлы:**
+- `config_flow.py` — переработка: корневая entry хранит credentials, sub-entries хранят модель/промпт/API
+- `__init__.py` — setup sub-entries
+- `conversation.py`, `ai_task.py` — привязка к sub-entry
+
+**Референсы:**
+- https://developers.home-assistant.io/docs/config_entries/subentries
+- `homeassistant.components.openai_conversation` (реализация через sub-entries)
+
+---
+
+## 3. Фаза 2 — Дифференциация (v1.0 – v1.3)
+
+Цель: добавить уникальные возможности, которых нет у большинства конкурентов.
+
+### v1.0 — Vision / мультимодальность
+
+**Приоритет:** Средний
+**Сложность:** Средняя
+**Зависимости:** v0.8 (нужны провайдеры с vision: GigaChat 2.0, OpenAI, Ollama)
+
+**Что:**
+- Отправка изображений с камер HA в LLM
+- Анализ: "Кто у двери?", "Что показывает камера во дворе?"
+- Поддержка: GigaChat 2.0 (мультимодальный), OpenAI GPT-4o/4.1, Ollama (LLaVA, Gemma Vision)
+
+**Реализация:**
+- Получение snapshot с камеры через `camera.async_get_image()`
+- Передача base64 изображения в LLM через LangChain `HumanMessage(content=[{"type": "image_url", ...}])`
+- Новый tool `get_camera_snapshot` или интеграция с Frigate events
+
+---
+
+### v1.1 — Генерация изображений (GigaChat Kandinsky + YandexART)
+
+**Приоритет:** Средний
+**Сложность:** Средняя
+**Зависимости:** нет
+
+**Что:**
+- GigaChat 2.0 имеет встроенную генерацию через Kandinsky
+- YandexGPT имеет YandexART API
+- Результат: `image` entity или сервис `gigachain.generate_image`
+
+**Реализация:**
+- Для GigaChat: уже поддерживается через API (модель сама решает, когда генерировать)
+- Для YandexART: отдельный API вызов
+- Сохранение результата в `/media/` или отправка через notify
+
+---
+
+### v1.2 — MCP (Model Context Protocol)
+
+**Приоритет:** Средний
+**Сложность:** Средняя-высокая
+**Зависимости:** v0.7 (Assist API)
+
+**Что:**
+- Подключение внешних MCP серверов как дополнительных tools для LLM
+- Все официальные интеграции HA поддерживают MCP с 2025.8
+- Примеры: новости, погода из внешних API, todo-листы, файловая система
+
+**Реализация:**
+- HA уже предоставляет MCP tools через `chat_log.llm_api.tools` — если пользователь настроил MCP в HA, tools автоматически доступны через Assist API
+- Дополнительно: собственный MCP client для LangChain tools (через `langchain-mcp`)
+
+---
+
+### v1.3 — Доступ к истории состояний
+
+**Приоритет:** Средний
+**Сложность:** Средняя
+**Зависимости:** v0.7 (tool calling)
+
+**Что:**
+- LLM может запрашивать историю состояний entity: "Какая температура была вчера?", "Когда последний раз открывали дверь?"
+- У Extended OpenAI Conversation это одна из ключевых фич
+
+**Реализация:**
+- Добавить custom tool `get_history(entity_id, start_time, end_time)`
+- Использовать `homeassistant.components.recorder` для получения данных
+- Форматирование результата в текст для LLM
+
+---
+
+## 4. Фаза 3 — Лидерство (v1.4+)
+
+Цель: уникальные фичи, которых нет ни у кого.
+
+### v1.4 — Multi-agent система
+
+**Приоритет:** Низкий
+**Сложность:** Высокая
+
+**Что:**
+- Dispatcher Agent маршрутизирует запросы между специализированными агентами
+- Агент управления устройствами (дешёвая быстрая модель)
+- Агент аналитики (reasoning модель)
+- Агент мультимедиа (vision модель)
+- Реализация через LangGraph
+
+---
+
+### v1.5 — Telegram-бот
+
+**Приоритет:** Низкий
+**Сложность:** Низкая
+
+**Что:**
+- Использование GigaChain как backend для Telegram-бота
+- Управление домом через Telegram
+- Отправка уведомлений с анализом камер
+
+---
+
+### v1.6 — STT/TTS интеграция
+
+**Приоритет:** Низкий
+**Сложность:** Средняя
+
+**Что:**
+- Связка с Yandex SpeechKit для STT/TTS на русском
+- GigaChat TTS (когда появится)
+- Полный voice pipeline: микрофон → STT → GigaChain → TTS → динамик
+
+---
+
+### v1.7 — Skill-система
+
+**Приоритет:** Низкий
+**Сложность:** Высокая
+
+**Что:**
+- Загружаемые "навыки" из директории (как у Extended OpenAI)
+- YAML-описание навыка: промпт + tools + trigger
+- Маркетплейс навыков (community-driven)
+
+---
+
+### v1.8 — Prompt caching
+
+**Приоритет:** Низкий
+**Сложность:** Низкая
+
+**Что:**
+- Кэширование системного промпта для ускорения повторных запросов
+- Экономия токенов при повторяющихся вызовах
+- Реализация: hash промпта → cached response для идентичных запросов
+
+---
+
+## 5. Технические детали по задачам
+
+### Зависимости для новых провайдеров
+
+| Провайдер | pip-пакет | LangChain класс | Min version |
+|-----------|-----------|-----------------|-------------|
+| Ollama | `langchain-ollama` | `ChatOllama` | >=0.3.0 |
+| DeepSeek | `langchain-deepseek` | `ChatDeepSeek` | >=0.1.0 |
+| Anthropic | `langchain-anthropic` | `ChatAnthropic` | >=0.3.0 |
+
+### Рекомендуемые локальные модели (для Ollama)
+
+| Модель | RAM | Лучше всего для | Язык |
+|--------|-----|-----------------|------|
+| Home-3B-v3 | ~2GB | Device control (97% точность) | EN |
+| T-Lite 7B | ~4GB | Русскоязычный чат | RU |
+| T-Pro 2.0 32B | ~18GB | Русский reasoning, tool calling | RU |
+| Qwen3 4B | ~3GB | Мультиязычный, tool calling | RU/EN/ZH |
+| Gemma 3 4B | ~3GB | Vision + чат | EN |
+
+### Целевые метрики по фазам
+
+| Фаза | Версия | Тестов | Провайдеров | Ключевая фича |
+|-------|--------|--------|-------------|---------------|
+| Текущая | 0.6.0 | 34 | 3 | Assist API |
+| Фаза 1 | 0.9.0 | ~60 | 6 | AI Task + Ollama + Sub-entries |
+| Фаза 2 | 1.3.0 | ~80 | 6 | Vision + MCP + Image Gen |
+| Фаза 3 | 1.8.0 | ~100 | 6+ | Multi-agent + Telegram + Skills |
+
+---
+
+```mermaid
+gantt
+ title GigaChain Roadmap 2026
+ dateFormat YYYY-MM
+ axisFormat %b %Y
+
+ section Фаза 1 — Паритет
+ v0.7 AI Task entity :a1, 2026-03, 2026-04
+ v0.8 Ollama + DeepSeek + Anthropic :a2, 2026-04, 2026-05
+ v0.9 Sub-entries :a3, 2026-05, 2026-06
+
+ section Фаза 2 — Дифференциация
+ v1.0 Vision :b1, 2026-06, 2026-07
+ v1.1 Image Generation :b2, 2026-07, 2026-08
+ v1.2 MCP :b3, 2026-07, 2026-08
+ v1.3 History Access :b4, 2026-08, 2026-09
+
+ section Фаза 3 — Лидерство
+ v1.4 Multi-agent :c1, 2026-09, 2026-11
+ v1.5 Telegram Bot :c2, 2026-10, 2026-11
+ v1.6 STT/TTS :c3, 2026-11, 2026-12
+ v1.7 Skill System :c4, 2026-12, 2027-02
+```
diff --git a/hacs.json b/hacs.json
index 797bcf4..1621fe2 100644
--- a/hacs.json
+++ b/hacs.json
@@ -1,4 +1,4 @@
{
- "name": "GigaChain",
- "render_readme" : true
+ "name": "SmartChain",
+ "render_readme": true
}
diff --git a/tests/conftest.py b/tests/conftest.py
index dee41d7..46f7230 100644
--- a/tests/conftest.py
+++ b/tests/conftest.py
@@ -1,4 +1,4 @@
-"""Fixtures for GigaChain tests."""
+"""Fixtures for SmartChain tests."""
from unittest.mock import AsyncMock, MagicMock, patch
@@ -8,7 +8,7 @@
from homeassistant.setup import async_setup_component
from langchain_core.messages import AIMessage, AIMessageChunk
-from custom_components.gigachain.const import (
+from custom_components.smartchain.const import (
CONF_API_KEY,
CONF_ENGINE,
DOMAIN,
@@ -75,7 +75,7 @@ def mock_config_entry():
def mock_validate_client():
"""Mock validate_client to skip actual API calls."""
with patch(
- "custom_components.gigachain.config_flow.validate_client",
+ "custom_components.smartchain.config_flow.validate_client",
new_callable=AsyncMock,
) as mock:
yield mock
@@ -85,7 +85,7 @@ def mock_validate_client():
def mock_get_client(mock_llm_client):
"""Mock get_client to return a fake LLM client."""
with patch(
- "custom_components.gigachain.get_client",
+ "custom_components.smartchain.get_client",
new_callable=AsyncMock,
return_value=mock_llm_client,
) as mock:
diff --git a/tests/test_config_flow.py b/tests/test_config_flow.py
index 62c280a..d53fe4b 100644
--- a/tests/test_config_flow.py
+++ b/tests/test_config_flow.py
@@ -1,4 +1,4 @@
-"""Tests for GigaChain config flow."""
+"""Tests for SmartChain config flow."""
from unittest.mock import AsyncMock, patch
@@ -9,7 +9,7 @@
from homeassistant.data_entry_flow import FlowResultType
from httpx import ConnectError
-from custom_components.gigachain.const import (
+from custom_components.smartchain.const import (
CONF_API_KEY,
CONF_ENGINE,
CONF_FOLDER_ID,
@@ -133,7 +133,7 @@ async def test_openai_full_flow(
async def test_gigachat_connect_error(hass: HomeAssistant) -> None:
"""Test GigaChat config flow handles connection error."""
with patch(
- "custom_components.gigachain.config_flow.validate_client",
+ "custom_components.smartchain.config_flow.validate_client",
side_effect=ConnectError("Connection failed"),
):
result = await hass.config_entries.flow.async_init(
@@ -153,7 +153,7 @@ async def test_gigachat_connect_error(hass: HomeAssistant) -> None:
async def test_gigachat_invalid_response(hass: HomeAssistant) -> None:
"""Test GigaChat config flow handles invalid response."""
with patch(
- "custom_components.gigachain.config_flow.validate_client",
+ "custom_components.smartchain.config_flow.validate_client",
side_effect=ResponseError("Unauthorized"),
):
result = await hass.config_entries.flow.async_init(
@@ -173,7 +173,7 @@ async def test_gigachat_invalid_response(hass: HomeAssistant) -> None:
async def test_gigachat_unknown_error(hass: HomeAssistant) -> None:
"""Test GigaChat config flow handles unknown error."""
with patch(
- "custom_components.gigachain.config_flow.validate_client",
+ "custom_components.smartchain.config_flow.validate_client",
side_effect=RuntimeError("Something unexpected"),
):
result = await hass.config_entries.flow.async_init(
@@ -195,7 +195,7 @@ async def test_skip_validation(
) -> None:
"""Test config flow with skip_validation=True skips API call."""
with patch(
- "custom_components.gigachain.config_flow.validate_client",
+ "custom_components.smartchain.config_flow.validate_client",
new_callable=AsyncMock,
) as mock_validate:
result = await hass.config_entries.flow.async_init(
diff --git a/tests/test_init.py b/tests/test_init.py
index 83c78a2..db9826f 100644
--- a/tests/test_init.py
+++ b/tests/test_init.py
@@ -1,5 +1,6 @@
-"""Tests for GigaChain conversation entity."""
+"""Tests for SmartChain conversation entity."""
+import json
from unittest.mock import AsyncMock, MagicMock, patch
import pytest
@@ -7,20 +8,29 @@
from homeassistant.components.conversation.chat_log import (
AssistantContent,
SystemContent,
+ ToolResultContent,
UserContent,
)
from homeassistant.core import Context, HomeAssistant
-from homeassistant.helpers import intent
-from langchain_core.messages import AIMessage, AIMessageChunk, HumanMessage, SystemMessage
+from homeassistant.helpers import intent, llm
+from langchain_core.messages import (
+ AIMessage,
+ AIMessageChunk,
+ HumanMessage,
+ SystemMessage,
+ ToolMessage,
+)
-from custom_components.gigachain.conversation import (
- GigaChainConversationEntity,
+from custom_components.smartchain.conversation import (
+ SmartChainConversationEntity,
_async_langchain_stream,
_chatlog_to_langchain,
+ _ha_tool_to_dict,
)
-from custom_components.gigachain.const import (
+from custom_components.smartchain.const import (
CONF_CHAT_HISTORY,
CONF_ENGINE,
+ CONF_LLM_HASS_API,
CONF_PROCESS_BUILTIN_SENTENCES,
CONF_PROMPT,
ID_GIGACHAT,
@@ -49,8 +59,9 @@ def _make_chat_log(conversation_id="test-conv-id", user_text="Hello, assistant!"
UserContent(content=user_text),
]
chat_log.async_add_assistant_content_without_tools = MagicMock()
+ chat_log.llm_api = None
+ chat_log.unresponded_tool_results = False
- # Support streaming: async_add_delta_content_stream collects deltas into AssistantContent
async def _mock_add_delta_stream(agent_id, stream):
collected = ""
async for delta in stream:
@@ -81,8 +92,8 @@ def mock_entry(mock_llm_client):
@pytest.fixture
def entity(hass: HomeAssistant, mock_entry):
- """Create a GigaChainConversationEntity."""
- ent = GigaChainConversationEntity(mock_entry)
+ """Create a SmartChainConversationEntity."""
+ ent = SmartChainConversationEntity(mock_entry)
ent.hass = hass
return ent
@@ -116,7 +127,6 @@ async def test_handle_message_sets_system_prompt(
"""Test that system prompt is set in ChatLog."""
await entity._async_handle_message(user_input, mock_chat_log)
- # content[0] should be replaced with the rendered system prompt
assert isinstance(mock_chat_log.content[0], SystemContent)
assert "test assistant" in mock_chat_log.content[0].content
@@ -127,7 +137,6 @@ async def test_handle_message_sends_correct_messages_to_llm(
"""Test that LLM receives correct LangChain messages from ChatLog."""
await entity._async_handle_message(user_input, mock_chat_log)
- # Check what was passed to client.astream
call_args = entity.entry.runtime_data.astream.call_args[0][0]
assert len(call_args) == 2 # system + human
assert isinstance(call_args[0], SystemMessage)
@@ -174,10 +183,9 @@ async def test_handle_message_history_disabled(
}
entry.runtime_data = mock_llm_client
- ent = GigaChainConversationEntity(entry)
+ ent = SmartChainConversationEntity(entry)
ent.hass = hass
- # ChatLog has history, but history is disabled
chat_log = _make_chat_log()
chat_log.content = [
SystemContent(content=""),
@@ -188,9 +196,8 @@ async def test_handle_message_history_disabled(
await ent._async_handle_message(user_input, chat_log)
- # Only system + current user message (not old history)
call_args = mock_llm_client.astream.call_args[0][0]
- assert len(call_args) == 2 # system + human (no history)
+ assert len(call_args) == 2
assert isinstance(call_args[0], SystemMessage)
assert isinstance(call_args[1], HumanMessage)
assert call_args[1].content == "Hello, assistant!"
@@ -230,12 +237,12 @@ async def test_handle_message_with_builtin_not_recognized(
mock_default_response = MagicMock(spec=ConversationResult)
mock_default_response.response = MagicMock()
- mock_default_response.response.intent = None # Not recognized
+ mock_default_response.response.intent = None
mock_default_agent = AsyncMock()
mock_default_agent.async_process.return_value = mock_default_response
- ent = GigaChainConversationEntity(entry)
+ ent = SmartChainConversationEntity(entry)
ent.hass = hass
with patch(
@@ -263,7 +270,7 @@ async def test_handle_message_builtin_recognized(
entry.runtime_data = mock_llm_client
mock_intent_response = MagicMock()
- mock_intent_response.intent = MagicMock() # Truthy = recognized
+ mock_intent_response.intent = MagicMock()
mock_intent_response.speech = {"plain": {"speech": "HA handled this"}}
mock_default_response = MagicMock(spec=ConversationResult)
@@ -272,7 +279,7 @@ async def test_handle_message_builtin_recognized(
mock_default_agent = AsyncMock()
mock_default_agent.async_process.return_value = mock_default_response
- ent = GigaChainConversationEntity(entry)
+ ent = SmartChainConversationEntity(entry)
ent.hass = hass
with patch(
@@ -333,7 +340,7 @@ def test_chatlog_to_langchain_skips_empty_assistant() -> None:
messages = _chatlog_to_langchain(chat_log)
- assert len(messages) == 2 # system + human (empty assistant skipped)
+ assert len(messages) == 2
async def test_async_langchain_stream() -> None:
@@ -369,8 +376,141 @@ async def _fake_astream(messages):
async for delta in _async_langchain_stream(client, []):
deltas.append(delta)
- # First chunk has role but no content — still yielded because it has "role"
- # Second chunk has content
assert len(deltas) == 2
assert deltas[0] == {"role": "assistant"}
assert deltas[1] == {"content": "data"}
+
+
+def test_chatlog_to_langchain_with_tool_calls() -> None:
+ """Test conversion of ChatLog with tool calls and tool results."""
+ tool_input = llm.ToolInput(
+ tool_name="HassTurnOn",
+ tool_args={"entity_id": "light.kitchen"},
+ id="call_123",
+ )
+ chat_log = MagicMock()
+ chat_log.content = [
+ SystemContent(content="System prompt"),
+ UserContent(content="Turn on kitchen light"),
+ AssistantContent(
+ agent_id="test",
+ content="",
+ tool_calls=[tool_input],
+ ),
+ ToolResultContent(
+ agent_id="test",
+ tool_call_id="call_123",
+ tool_name="HassTurnOn",
+ tool_result={"success": True},
+ ),
+ AssistantContent(agent_id="test", content="Done!"),
+ ]
+
+ messages = _chatlog_to_langchain(chat_log)
+
+ assert len(messages) == 5
+ assert isinstance(messages[0], SystemMessage)
+ assert isinstance(messages[1], HumanMessage)
+ assert isinstance(messages[2], AIMessage)
+ assert len(messages[2].tool_calls) == 1
+ assert messages[2].tool_calls[0]["name"] == "HassTurnOn"
+ assert messages[2].tool_calls[0]["id"] == "call_123"
+ assert isinstance(messages[3], ToolMessage)
+ assert messages[3].tool_call_id == "call_123"
+ assert json.loads(messages[3].content) == {"success": True}
+ assert isinstance(messages[4], AIMessage)
+ assert messages[4].content == "Done!"
+
+
+def test_ha_tool_to_dict() -> None:
+ """Test conversion of HA llm.Tool to dict for LangChain."""
+ import voluptuous as vol
+
+ class MockTool(llm.Tool):
+ name = "HassTurnOn"
+ description = "Turn on a device"
+ parameters = vol.Schema({
+ vol.Required("entity_id"): str,
+ })
+
+ async def async_call(self, hass, tool_input, llm_context):
+ return {"success": True}
+
+ tool = MockTool()
+ result = _ha_tool_to_dict(tool)
+
+ assert result["name"] == "HassTurnOn"
+ assert result["description"] == "Turn on a device"
+ assert "properties" in result["parameters"]
+ assert "entity_id" in result["parameters"]["properties"]
+
+
+async def test_async_langchain_stream_with_tool_calls() -> None:
+ """Test that tool_calls from LLM are converted to HA ToolInput in stream."""
+ client = MagicMock()
+
+ async def _fake_astream(messages):
+ yield AIMessageChunk(
+ content="",
+ tool_calls=[
+ {"id": "call_1", "name": "HassTurnOn", "args": {"entity_id": "light.kitchen"}},
+ ],
+ )
+
+ client.astream = _fake_astream
+
+ deltas = []
+ async for delta in _async_langchain_stream(client, []):
+ deltas.append(delta)
+
+ assert len(deltas) == 1
+ assert deltas[0]["role"] == "assistant"
+ assert "tool_calls" in deltas[0]
+ assert len(deltas[0]["tool_calls"]) == 1
+ tc = deltas[0]["tool_calls"][0]
+ assert isinstance(tc, llm.ToolInput)
+ assert tc.tool_name == "HassTurnOn"
+ assert tc.tool_args == {"entity_id": "light.kitchen"}
+ assert tc.id == "call_1"
+
+
+async def test_handle_message_with_llm_api(
+ hass: HomeAssistant, mock_llm_client, user_input
+) -> None:
+ """Test _async_handle_message with LLM Hass API configured."""
+ entry = MagicMock()
+ entry.entry_id = "test_entry"
+ entry.data = {CONF_ENGINE: ID_GIGACHAT, "api_key": "test"}
+ entry.options = {
+ CONF_PROMPT: "Test prompt.",
+ CONF_CHAT_HISTORY: True,
+ CONF_PROCESS_BUILTIN_SENTENCES: False,
+ CONF_LLM_HASS_API: "assist",
+ }
+ entry.runtime_data = mock_llm_client
+
+ ent = SmartChainConversationEntity(entry)
+ ent.hass = hass
+
+ chat_log = _make_chat_log()
+
+ with patch.object(
+ chat_log,
+ "async_provide_llm_data",
+ new_callable=AsyncMock,
+ ) as mock_provide:
+ chat_log.llm_api = None
+ await ent._async_handle_message(user_input, chat_log)
+
+ mock_provide.assert_called_once()
+ assert mock_provide.call_args[0][1] == "assist"
+
+
+async def test_handle_message_no_llm_api_sets_prompt_manually(
+ hass: HomeAssistant, entity, user_input, mock_chat_log
+) -> None:
+ """Test that without LLM API configured, system prompt is set manually."""
+ await entity._async_handle_message(user_input, mock_chat_log)
+
+ assert isinstance(mock_chat_log.content[0], SystemContent)
+ assert "test assistant" in mock_chat_log.content[0].content
diff --git a/tests/test_setup.py b/tests/test_setup.py
index 3405533..465da89 100644
--- a/tests/test_setup.py
+++ b/tests/test_setup.py
@@ -1,4 +1,4 @@
-"""Tests for GigaChain integration setup and unload."""
+"""Tests for SmartChain integration setup and unload."""
from unittest.mock import AsyncMock, MagicMock, patch
@@ -6,7 +6,7 @@
from homeassistant.core import HomeAssistant
from pytest_homeassistant_custom_component.common import MockConfigEntry
-from custom_components.gigachain.const import (
+from custom_components.smartchain.const import (
CONF_API_KEY,
CONF_ENGINE,
DOMAIN,
@@ -49,7 +49,7 @@ async def test_setup_entry_gigachat(
) -> None:
"""Test successful setup of GigaChat entry."""
with patch(
- "custom_components.gigachain.get_client",
+ "custom_components.smartchain.get_client",
new_callable=AsyncMock,
return_value=mock_llm_client,
):
@@ -65,7 +65,7 @@ async def test_setup_entry_openai(
) -> None:
"""Test successful setup of OpenAI entry."""
with patch(
- "custom_components.gigachain.get_client",
+ "custom_components.smartchain.get_client",
new_callable=AsyncMock,
return_value=mock_llm_client,
):
@@ -81,7 +81,7 @@ async def test_unload_entry(
) -> None:
"""Test unloading a config entry."""
with patch(
- "custom_components.gigachain.get_client",
+ "custom_components.smartchain.get_client",
new_callable=AsyncMock,
return_value=mock_llm_client,
):
@@ -99,16 +99,14 @@ async def test_setup_creates_conversation_entity(
) -> None:
"""Test that setup creates a conversation entity."""
with patch(
- "custom_components.gigachain.get_client",
+ "custom_components.smartchain.get_client",
new_callable=AsyncMock,
return_value=mock_llm_client,
):
await hass.config_entries.async_setup(mock_gigachat_entry.entry_id)
await hass.async_block_till_done()
- # Check that a conversation entity was created
states = [s for s in hass.states.async_all() if s.domain == "conversation"]
- # Should have default HA agent + our GigaChain entity
assert len(states) >= 2
entity_ids = [s.entity_id for s in states]
- assert any("gigachain" in eid for eid in entity_ids)
+ assert any("smartchain" in eid for eid in entity_ids)
From b52e915965599a071edba0c2ff090c173d91967f Mon Sep 17 00:00:00 2001
From: dzerik
Date: Tue, 10 Mar 2026 18:45:24 +0300
Subject: [PATCH 22/26] docs: add CLAUDE.md project rules
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Project conventions, architecture overview, testing and naming rules.
🤖 Generated with Claude Code
Co-Authored-By: Claude
---
CLAUDE.md | 57 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 57 insertions(+)
create mode 100644 CLAUDE.md
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..8b5278c
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,57 @@
+# SmartChain — Project Rules
+
+## Project Overview
+SmartChain is a Home Assistant custom integration providing a multi-provider LLM conversation agent via LangChain.
+
+- **Domain**: `smartchain`
+- **HA Platform**: `Platform.CONVERSATION` (+ `Platform.AI_TASK` planned)
+- **Supported LLM providers**: GigaChat, YandexGPT, OpenAI
+- **Planned providers**: Ollama, DeepSeek, Anthropic
+- **GitHub**: https://github.com/dzerik/ha-smartchain
+
+## Architecture
+
+### Core Files
+- `custom_components/smartchain/__init__.py` — entry setup, client creation
+- `custom_components/smartchain/conversation.py` — `SmartChainConversationEntity` (streaming, tool calling)
+- `custom_components/smartchain/ai_task.py` — `SmartChainAITaskEntity` (data generation)
+- `custom_components/smartchain/config_flow.py` — Config Flow + Options Flow
+- `custom_components/smartchain/client_util.py` — LLM client factory (`get_client`, `validate_client`)
+- `custom_components/smartchain/const.py` — all constants, prompts, model lists
+
+### Key Patterns
+- **Streaming**: `client.astream()` -> `_async_langchain_stream()` -> `chat_log.async_add_delta_content_stream()`
+- **Tool calling**: HA `llm.Tool` -> `_ha_tool_to_dict()` -> `client.bind_tools()` -> loop until no `unresponded_tool_results`
+- **ChatLog conversion**: `_chatlog_to_langchain()` converts HA ChatLog content to LangChain message list
+- **System prompt**: With Assist API — `async_provide_llm_data()`, without — manual Jinja2 template + `DEFAULT_DEVICES_PROMPT`
+
+### Tests
+- `tests/test_config_flow.py` — 11 config flow tests
+- `tests/test_init.py` — 19 conversation entity tests
+- `tests/test_setup.py` — 4 setup/unload tests
+- Run: `python3 -m pytest tests/ -v`
+
+## Development Rules
+
+### Naming
+- Entity classes: `SmartChain*Entity` (e.g., `SmartChainConversationEntity`)
+- Imports: `from custom_components.smartchain.X import Y`
+- Domain constant: `DOMAIN = "smartchain"`
+
+### Testing
+- Always run tests before committing: `python3 -m pytest tests/ -v`
+- All tests must pass
+- Mock LLM clients with `MagicMock` + `astream` side_effect
+- Use `_make_chat_log()` helper for mock ChatLog with streaming support
+
+### Dependencies
+- `langchain-gigachat>=0.3.0` — GigaChat provider
+- `langchain-openai>=0.3.0` — OpenAI provider
+- `langchain-community>=0.4.0` — YandexGPT and others
+- `home-assistant-intents` — language support
+- `yandexcloud==0.295.0` — Yandex Cloud SDK
+
+### Version Policy
+- Manifest version in `custom_components/smartchain/manifest.json`
+- Follow semver: PATCH for fixes, MINOR for features, MAJOR for breaking changes
+- Current: 0.7.0
From 917ddec08e9334e5561277769657d5e8d8278d2e Mon Sep 17 00:00:00 2001
From: dzerik
Date: Tue, 10 Mar 2026 18:50:26 +0300
Subject: [PATCH 23/26] feat: register AI Task platform + add 7 AI Task tests +
lint fixes (v0.7.0)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
- Added Platform.AI_TASK to __init__.py PLATFORMS
- Added ai_task to manifest.json dependencies
- Fixed codeowners to @dzerik, documentation URLs to dzerik/ha-smartchain
- Created test_ai_task.py with 7 tests:
- test_ai_task_entity_init
- test_generate_data_basic
- test_generate_data_structured_json
- test_generate_data_structured_invalid_json
- test_generate_data_llm_error
- test_generate_data_with_tools
- test_generate_data_empty_response
- Fixed ruff lint (unused imports) and format issues
- Fixed noqa directives in test files
- Total: 41 tests, all passing
🤖 Generated with Claude Code
Co-Authored-By: Claude
---
custom_components/smartchain/__init__.py | 2 +-
custom_components/smartchain/ai_task.py | 6 +-
custom_components/smartchain/client_util.py | 38 +++-
custom_components/smartchain/config_flow.py | 228 +++++++++++--------
custom_components/smartchain/conversation.py | 8 +-
custom_components/smartchain/manifest.json | 8 +-
tests/__init__.py | 2 +-
tests/test_ai_task.py | 194 ++++++++++++++++
tests/test_init.py | 20 +-
tests/test_setup.py | 3 +-
10 files changed, 382 insertions(+), 127 deletions(-)
create mode 100644 tests/test_ai_task.py
diff --git a/custom_components/smartchain/__init__.py b/custom_components/smartchain/__init__.py
index 47d914b..455fa8c 100644
--- a/custom_components/smartchain/__init__.py
+++ b/custom_components/smartchain/__init__.py
@@ -19,7 +19,7 @@
LOGGER = logging.getLogger(__name__)
-PLATFORMS = [Platform.CONVERSATION]
+PLATFORMS = [Platform.CONVERSATION, Platform.AI_TASK]
async def update_listener(hass: HomeAssistant, entry: ConfigEntry) -> None:
diff --git a/custom_components/smartchain/ai_task.py b/custom_components/smartchain/ai_task.py
index 52d87ed..41ca2e5 100644
--- a/custom_components/smartchain/ai_task.py
+++ b/custom_components/smartchain/ai_task.py
@@ -9,7 +9,11 @@
from homeassistant.helpers.entity_platform import AddEntitiesCallback
from .const import MAX_TOOL_ITERATIONS
-from .conversation import _async_langchain_stream, _chatlog_to_langchain, _ha_tool_to_dict
+from .conversation import (
+ _async_langchain_stream,
+ _chatlog_to_langchain,
+ _ha_tool_to_dict,
+)
LOGGER = logging.getLogger(__name__)
diff --git a/custom_components/smartchain/client_util.py b/custom_components/smartchain/client_util.py
index df86287..a1a0184 100644
--- a/custom_components/smartchain/client_util.py
+++ b/custom_components/smartchain/client_util.py
@@ -7,17 +7,27 @@
from langchain_gigachat import GigaChat
from langchain_openai import ChatOpenAI
-from .const import (CONF_API_KEY, CONF_ENGINE, CONF_FOLDER_ID, CONF_PROFANITY,
- CONF_SKIP_VALIDATION, CONF_VERIFY_SSL, DEFAULT_PROFANITY,
- DEFAULT_VERIFY_SSL, ID_GIGACHAT,
- ID_YANDEX_GPT, ID_OPENAI, DEFAULT_MODEL)
+from .const import (
+ CONF_API_KEY,
+ CONF_ENGINE,
+ CONF_FOLDER_ID,
+ CONF_PROFANITY,
+ CONF_SKIP_VALIDATION,
+ CONF_VERIFY_SSL,
+ DEFAULT_PROFANITY,
+ DEFAULT_VERIFY_SSL,
+ ID_GIGACHAT,
+ ID_YANDEX_GPT,
+ ID_OPENAI,
+ DEFAULT_MODEL,
+)
LOGGER = logging.getLogger(__name__)
async def validate_client(
- hass: HomeAssistant,
- user_input: dict,
+ hass: HomeAssistant,
+ user_input: dict,
) -> None:
"""Validate LLM client connection."""
if user_input.get(CONF_SKIP_VALIDATION):
@@ -47,16 +57,20 @@ async def validate_client(
async def get_client(
- hass: HomeAssistant,
- engine: str,
- entry: ConfigEntry,
- common_args: dict,
+ hass: HomeAssistant,
+ engine: str,
+ entry: ConfigEntry,
+ common_args: dict,
):
"""Create LLM client based on engine type."""
if engine == ID_GIGACHAT:
common_args["credentials"] = entry.data[CONF_API_KEY]
- common_args["verify_ssl_certs"] = entry.options.get(CONF_VERIFY_SSL, DEFAULT_VERIFY_SSL)
- common_args["profanity_check"] = entry.options.get(CONF_PROFANITY, DEFAULT_PROFANITY)
+ common_args["verify_ssl_certs"] = entry.options.get(
+ CONF_VERIFY_SSL, DEFAULT_VERIFY_SSL
+ )
+ common_args["profanity_check"] = entry.options.get(
+ CONF_PROFANITY, DEFAULT_PROFANITY
+ )
client = GigaChat(**common_args)
elif engine == ID_YANDEX_GPT:
common_args["api_key"] = entry.data[CONF_API_KEY]
diff --git a/custom_components/smartchain/config_flow.py b/custom_components/smartchain/config_flow.py
index 93a2df5..51f111c 100644
--- a/custom_components/smartchain/config_flow.py
+++ b/custom_components/smartchain/config_flow.py
@@ -12,26 +12,49 @@
from homeassistant.config_entries import ConfigFlowResult
from homeassistant.core import callback
from homeassistant.helpers import selector
-from homeassistant.helpers.selector import (NumberSelector,
- NumberSelectorConfig,
- SelectSelectorMode,
- TemplateSelector)
+from homeassistant.helpers.selector import (
+ NumberSelector,
+ NumberSelectorConfig,
+ SelectSelectorMode,
+ TemplateSelector,
+)
from httpx import ConnectError
from homeassistant.helpers import llm
from .client_util import validate_client
-from .const import (CONF_API_KEY, CONF_CHAT_MODEL, CONF_CHAT_MODEL_USER,
- CONF_ENGINE, CONF_ENGINE_OPTIONS, CONF_FOLDER_ID,
- CONF_LLM_HASS_API, CONF_MAX_TOKENS, CONF_PROFANITY,
- CONF_PROMPT, CONF_SKIP_VALIDATION, CONF_TEMPERATURE,
- CONF_VERIFY_SSL, DEFAULT_CHAT_MODEL, DEFAULT_VERIFY_SSL,
- ENGINE_MODELS, DEFAULT_PROFANITY, DEFAULT_PROMPT,
- DEFAULT_SKIP_VALIDATION, DEFAULT_TEMPERATURE, DOMAIN,
- ID_GIGACHAT, ID_OPENAI, ID_YANDEX_GPT, UNIQUE_ID,
- CONF_PROCESS_BUILTIN_SENTENCES, DEFAULT_PROCESS_BUILTIN_SENTENCES,
- CONF_CHAT_HISTORY, DEFAULT_CHAT_HISTORY,
- UNIQUE_ID_GIGACHAT)
+from .const import (
+ CONF_API_KEY,
+ CONF_CHAT_MODEL,
+ CONF_CHAT_MODEL_USER,
+ CONF_ENGINE,
+ CONF_ENGINE_OPTIONS,
+ CONF_FOLDER_ID,
+ CONF_LLM_HASS_API,
+ CONF_MAX_TOKENS,
+ CONF_PROFANITY,
+ CONF_PROMPT,
+ CONF_SKIP_VALIDATION,
+ CONF_TEMPERATURE,
+ CONF_VERIFY_SSL,
+ DEFAULT_CHAT_MODEL,
+ DEFAULT_VERIFY_SSL,
+ ENGINE_MODELS,
+ DEFAULT_PROFANITY,
+ DEFAULT_PROMPT,
+ DEFAULT_SKIP_VALIDATION,
+ DEFAULT_TEMPERATURE,
+ DOMAIN,
+ ID_GIGACHAT,
+ ID_OPENAI,
+ ID_YANDEX_GPT,
+ UNIQUE_ID,
+ CONF_PROCESS_BUILTIN_SENTENCES,
+ DEFAULT_PROCESS_BUILTIN_SENTENCES,
+ CONF_CHAT_HISTORY,
+ DEFAULT_CHAT_HISTORY,
+ UNIQUE_ID_GIGACHAT,
+)
LOGGER = logging.getLogger(__name__)
@@ -45,18 +68,14 @@
STEP_API_KEY_SCHEMA = vol.Schema(
{
vol.Required(CONF_API_KEY): str,
- vol.Optional(
- CONF_SKIP_VALIDATION, default=DEFAULT_SKIP_VALIDATION
- ): bool,
+ vol.Optional(CONF_SKIP_VALIDATION, default=DEFAULT_SKIP_VALIDATION): bool,
}
)
STEP_YANDEXGPT_SCHEMA = vol.Schema(
{
vol.Required(CONF_API_KEY): str,
vol.Required(CONF_FOLDER_ID): str,
- vol.Optional(
- CONF_SKIP_VALIDATION, default=DEFAULT_SKIP_VALIDATION
- ): bool,
+ vol.Optional(CONF_SKIP_VALIDATION, default=DEFAULT_SKIP_VALIDATION): bool,
}
)
@@ -82,7 +101,7 @@ class ConfigFlow(config_entries.ConfigFlow, domain=DOMAIN):
VERSION = 1
async def async_step_user(
- self, user_input: dict[str, Any] | None = None
+ self, user_input: dict[str, Any] | None = None
) -> ConfigFlowResult:
"""Handle the initial step."""
if user_input is None:
@@ -95,22 +114,22 @@ async def async_step_user(
return self.async_show_form(step_id=engine, data_schema=ENGINE_SCHEMA[engine])
async def async_step_gigachat(
- self, user_input: dict[str, Any] | None = None
+ self, user_input: dict[str, Any] | None = None
) -> ConfigFlowResult:
return await self._common_model_async_step(ID_GIGACHAT, user_input)
async def async_step_yandexgpt(
- self, user_input: dict[str, Any] | None = None
+ self, user_input: dict[str, Any] | None = None
) -> ConfigFlowResult:
return await self._common_model_async_step(ID_YANDEX_GPT, user_input)
async def async_step_openai(
- self, user_input: dict[str, Any] | None = None
+ self, user_input: dict[str, Any] | None = None
) -> ConfigFlowResult:
return await self._common_model_async_step(ID_OPENAI, user_input)
async def _common_model_async_step(
- self, engine: str, user_input: dict[str, Any] | None
+ self, engine: str, user_input: dict[str, Any] | None
) -> ConfigFlowResult:
if user_input is None:
return self.async_show_form(
@@ -141,7 +160,7 @@ async def _common_model_async_step(
@staticmethod
@callback
def async_get_options_flow(
- config_entry: config_entries.ConfigEntry,
+ config_entry: config_entries.ConfigEntry,
) -> config_entries.OptionsFlow:
"""Create the options flow."""
return OptionsFlow(config_entry)
@@ -155,7 +174,7 @@ def __init__(self, config_entry: config_entries.ConfigEntry) -> None:
self.config_entry = config_entry
async def async_step_init(
- self, user_input: dict[str, Any] | None = None
+ self, user_input: dict[str, Any] | None = None
) -> ConfigFlowResult:
"""Manage the options."""
unique_id = self.config_entry.unique_id
@@ -168,7 +187,8 @@ async def async_step_init(
model = user_input.get(CONF_CHAT_MODEL)
if not model or not model.strip():
return self.async_show_form(
- step_id="init", data_schema=schema,
+ step_id="init",
+ data_schema=schema,
errors={"base": "model_required"},
)
@@ -185,7 +205,7 @@ async def async_step_init(
def common_config_option_schema(
- hass, unique_id: str, options: MappingProxyType[str, Any]
+ hass, unique_id: str, options: MappingProxyType[str, Any]
) -> vol.Schema:
"""Return a schema for SmartChain completion options."""
if not options:
@@ -196,73 +216,95 @@ def common_config_option_schema(
for api in llm.async_get_apis(hass)
]
- schema = vol.Schema({
- vol.Optional(
- CONF_CHAT_MODEL,
- description={
- "suggested_value": options.get(CONF_CHAT_MODEL),
- },
- default="none",
- ): selector.SelectSelector(
- selector.SelectSelectorConfig(mode=SelectSelectorMode("dropdown"), options=ENGINE_MODELS[unique_id]),
- ),
- vol.Optional(
- CONF_CHAT_MODEL_USER,
- description={
- "suggested_value": options.get(CONF_CHAT_MODEL_USER)
- },
- ): str,
- vol.Optional(
- CONF_LLM_HASS_API,
- ): selector.SelectSelector(
- selector.SelectSelectorConfig(
- options=hass_apis, multiple=True, mode=SelectSelectorMode("dropdown")
+ schema = vol.Schema(
+ {
+ vol.Optional(
+ CONF_CHAT_MODEL,
+ description={
+ "suggested_value": options.get(CONF_CHAT_MODEL),
+ },
+ default="none",
+ ): selector.SelectSelector(
+ selector.SelectSelectorConfig(
+ mode=SelectSelectorMode("dropdown"),
+ options=ENGINE_MODELS[unique_id],
+ ),
),
- ),
- vol.Optional(
- CONF_PROMPT,
- description={"suggested_value": options.get(CONF_PROMPT, DEFAULT_PROMPT)},
- default=DEFAULT_PROMPT,
- ): TemplateSelector(),
- vol.Optional(
- CONF_TEMPERATURE,
- description={
- "suggested_value": options.get(CONF_TEMPERATURE, DEFAULT_TEMPERATURE)
- },
- default=DEFAULT_TEMPERATURE,
- ): NumberSelector(NumberSelectorConfig(min=0, max=1, step=0.05)),
- vol.Optional(
- CONF_MAX_TOKENS,
- description={
- "suggested_value": options.get(CONF_MAX_TOKENS)
- },
- ): int,
- vol.Optional(
- CONF_PROCESS_BUILTIN_SENTENCES,
- description={
- "suggested_value": options.get(CONF_PROCESS_BUILTIN_SENTENCES, DEFAULT_PROCESS_BUILTIN_SENTENCES)
- },
- default=DEFAULT_PROCESS_BUILTIN_SENTENCES): bool,
- vol.Optional(
- CONF_CHAT_HISTORY,
- description={
- "suggested_value": options.get(CONF_CHAT_HISTORY, DEFAULT_CHAT_HISTORY)
- },
- default=DEFAULT_CHAT_HISTORY): bool
- })
+ vol.Optional(
+ CONF_CHAT_MODEL_USER,
+ description={"suggested_value": options.get(CONF_CHAT_MODEL_USER)},
+ ): str,
+ vol.Optional(
+ CONF_LLM_HASS_API,
+ ): selector.SelectSelector(
+ selector.SelectSelectorConfig(
+ options=hass_apis,
+ multiple=True,
+ mode=SelectSelectorMode("dropdown"),
+ ),
+ ),
+ vol.Optional(
+ CONF_PROMPT,
+ description={
+ "suggested_value": options.get(CONF_PROMPT, DEFAULT_PROMPT)
+ },
+ default=DEFAULT_PROMPT,
+ ): TemplateSelector(),
+ vol.Optional(
+ CONF_TEMPERATURE,
+ description={
+ "suggested_value": options.get(
+ CONF_TEMPERATURE, DEFAULT_TEMPERATURE
+ )
+ },
+ default=DEFAULT_TEMPERATURE,
+ ): NumberSelector(NumberSelectorConfig(min=0, max=1, step=0.05)),
+ vol.Optional(
+ CONF_MAX_TOKENS,
+ description={"suggested_value": options.get(CONF_MAX_TOKENS)},
+ ): int,
+ vol.Optional(
+ CONF_PROCESS_BUILTIN_SENTENCES,
+ description={
+ "suggested_value": options.get(
+ CONF_PROCESS_BUILTIN_SENTENCES,
+ DEFAULT_PROCESS_BUILTIN_SENTENCES,
+ )
+ },
+ default=DEFAULT_PROCESS_BUILTIN_SENTENCES,
+ ): bool,
+ vol.Optional(
+ CONF_CHAT_HISTORY,
+ description={
+ "suggested_value": options.get(
+ CONF_CHAT_HISTORY, DEFAULT_CHAT_HISTORY
+ )
+ },
+ default=DEFAULT_CHAT_HISTORY,
+ ): bool,
+ }
+ )
if unique_id == UNIQUE_ID_GIGACHAT:
schema = schema.extend(
{
- vol.Optional(CONF_PROFANITY,
- description={
- "suggested_value": options.get(CONF_PROFANITY, DEFAULT_PROFANITY)
- },
- default=DEFAULT_PROFANITY): bool,
- vol.Optional(CONF_VERIFY_SSL,
- description={
- "suggested_value": options.get(CONF_VERIFY_SSL, DEFAULT_VERIFY_SSL)
- },
- default=DEFAULT_VERIFY_SSL): bool,
+ vol.Optional(
+ CONF_PROFANITY,
+ description={
+ "suggested_value": options.get(
+ CONF_PROFANITY, DEFAULT_PROFANITY
+ )
+ },
+ default=DEFAULT_PROFANITY,
+ ): bool,
+ vol.Optional(
+ CONF_VERIFY_SSL,
+ description={
+ "suggested_value": options.get(
+ CONF_VERIFY_SSL, DEFAULT_VERIFY_SSL
+ )
+ },
+ default=DEFAULT_VERIFY_SSL,
+ ): bool,
}
)
return schema
diff --git a/custom_components/smartchain/conversation.py b/custom_components/smartchain/conversation.py
index c234fcd..36e302e 100644
--- a/custom_components/smartchain/conversation.py
+++ b/custom_components/smartchain/conversation.py
@@ -121,8 +121,8 @@ async def _async_handle_message(
default_response = await default_agent.async_process(user_input)
if default_response.response.intent:
- speech = (
- default_response.response.speech.get("plain", {}).get("speech", "")
+ speech = default_response.response.speech.get("plain", {}).get(
+ "speech", ""
)
chat_log.async_add_assistant_content_without_tools(
AssistantContent(
@@ -141,9 +141,7 @@ async def _async_handle_message(
bound_client = client.bind_tools(tools) if tools else client
for _iteration in range(MAX_TOOL_ITERATIONS):
- chat_history_enabled = options.get(
- CONF_CHAT_HISTORY, DEFAULT_CHAT_HISTORY
- )
+ chat_history_enabled = options.get(CONF_CHAT_HISTORY, DEFAULT_CHAT_HISTORY)
if chat_history_enabled:
messages = _chatlog_to_langchain(chat_log)
else:
diff --git a/custom_components/smartchain/manifest.json b/custom_components/smartchain/manifest.json
index e56c4da..ce4f43c 100644
--- a/custom_components/smartchain/manifest.json
+++ b/custom_components/smartchain/manifest.json
@@ -1,14 +1,14 @@
{
"domain": "smartchain",
"name": "SmartChain",
- "codeowners": ["@gritaro"],
+ "codeowners": ["@dzerik"],
"config_flow": true,
- "dependencies": ["conversation"],
- "documentation": "https://github.com/gritaro/ha-smartchain",
+ "dependencies": ["ai_task", "conversation"],
+ "documentation": "https://github.com/dzerik/ha-smartchain",
"homekit": {},
"integration_type": "service",
"iot_class": "cloud_polling",
- "issue_tracker": "https://github.com/gritaro/ha-smartchain/issues",
+ "issue_tracker": "https://github.com/dzerik/ha-smartchain/issues",
"requirements": [
"home-assistant-intents",
"langchain-gigachat>=0.3.0",
diff --git a/tests/__init__.py b/tests/__init__.py
index 149000f..54ffec7 100644
--- a/tests/__init__.py
+++ b/tests/__init__.py
@@ -1 +1 @@
-"""Tests for the GigaChain integration."""
+"""Tests for the SmartChain integration."""
diff --git a/tests/test_ai_task.py b/tests/test_ai_task.py
new file mode 100644
index 0000000..ae802e6
--- /dev/null
+++ b/tests/test_ai_task.py
@@ -0,0 +1,194 @@
+"""Tests for SmartChain AI Task entity."""
+
+from unittest.mock import MagicMock
+
+import pytest
+from homeassistant.components import ai_task
+from homeassistant.components.conversation.chat_log import (
+ AssistantContent,
+ SystemContent,
+ UserContent,
+)
+from homeassistant.exceptions import HomeAssistantError
+from langchain_core.messages import AIMessageChunk
+
+from custom_components.smartchain.ai_task import SmartChainAITaskEntity
+from custom_components.smartchain.const import CONF_ENGINE, ID_GIGACHAT
+
+
+def _make_chat_log(conversation_id="test-conv-id"):
+ """Create a mock ChatLog for AI Task tests."""
+ chat_log = MagicMock()
+ chat_log.conversation_id = conversation_id
+ chat_log.content = [
+ SystemContent(content="You are a Home Assistant expert."),
+ UserContent(content="Summarize the weather"),
+ ]
+ chat_log.llm_api = None
+ chat_log.unresponded_tool_results = False
+
+ async def _mock_add_delta_stream(agent_id, stream):
+ collected = ""
+ async for delta in stream:
+ if "content" in delta:
+ collected += delta["content"]
+ content = AssistantContent(agent_id=agent_id, content=collected)
+ chat_log.content.append(content)
+ yield content
+
+ chat_log.async_add_delta_content_stream = _mock_add_delta_stream
+ return chat_log
+
+
+def _make_gen_data_task(instructions="Summarize the weather", structure=None):
+ """Create a GenDataTask."""
+ return ai_task.GenDataTask(
+ name="test_task",
+ instructions=instructions,
+ structure=structure,
+ )
+
+
+@pytest.fixture
+def ai_task_entity(mock_llm_client):
+ """Create a SmartChainAITaskEntity."""
+ entry = MagicMock()
+ entry.entry_id = "test_entry"
+ entry.data = {CONF_ENGINE: ID_GIGACHAT, "api_key": "test"}
+ entry.options = {}
+ entry.runtime_data = mock_llm_client
+ ent = SmartChainAITaskEntity(entry)
+ ent.hass = MagicMock()
+ ent._attr_entity_id = "ai_task.smartchain_test"
+ return ent
+
+
+async def test_ai_task_entity_init(ai_task_entity) -> None:
+ """Test AI Task entity initialization."""
+ assert ai_task_entity._attr_unique_id == "test_entry_ai_task"
+ assert (
+ ai_task_entity._attr_supported_features
+ == ai_task.AITaskEntityFeature.GENERATE_DATA
+ )
+ assert ai_task_entity._attr_has_entity_name is True
+
+
+async def test_generate_data_basic(ai_task_entity) -> None:
+ """Test basic data generation returns text result."""
+ chat_log = _make_chat_log()
+ task = _make_gen_data_task()
+
+ result = await ai_task_entity._async_generate_data(task, chat_log)
+
+ assert isinstance(result, ai_task.GenDataTaskResult)
+ assert result.conversation_id == "test-conv-id"
+ assert result.data == "Test response from LLM"
+
+
+async def test_generate_data_structured_json(ai_task_entity) -> None:
+ """Test structured output parses JSON response."""
+ import voluptuous as vol
+
+ # Mock client to return JSON
+ async def _json_astream(messages):
+ yield AIMessageChunk(content='{"temperature": 22, "condition": "sunny"}')
+
+ ai_task_entity.entry.runtime_data.astream = MagicMock(side_effect=_json_astream)
+
+ chat_log = _make_chat_log()
+ task = _make_gen_data_task(
+ instructions="Get weather data",
+ structure=vol.Schema(
+ {
+ vol.Required("temperature"): int,
+ vol.Required("condition"): str,
+ }
+ ),
+ )
+
+ result = await ai_task_entity._async_generate_data(task, chat_log)
+
+ assert isinstance(result, ai_task.GenDataTaskResult)
+ assert result.data == {"temperature": 22, "condition": "sunny"}
+
+
+async def test_generate_data_structured_invalid_json(ai_task_entity) -> None:
+ """Test structured output raises error on invalid JSON."""
+ import voluptuous as vol
+
+ async def _bad_astream(messages):
+ yield AIMessageChunk(content="not json at all")
+
+ ai_task_entity.entry.runtime_data.astream = MagicMock(side_effect=_bad_astream)
+
+ chat_log = _make_chat_log()
+ task = _make_gen_data_task(
+ instructions="Get data",
+ structure=vol.Schema({vol.Required("key"): str}),
+ )
+
+ with pytest.raises(HomeAssistantError, match="Failed to parse"):
+ await ai_task_entity._async_generate_data(task, chat_log)
+
+
+async def test_generate_data_llm_error(ai_task_entity) -> None:
+ """Test that LLM errors are raised as HomeAssistantError."""
+
+ async def _error_astream(messages):
+ raise RuntimeError("LLM API down")
+ yield # noqa: F841
+
+ ai_task_entity.entry.runtime_data.astream = MagicMock(side_effect=_error_astream)
+
+ chat_log = _make_chat_log()
+ task = _make_gen_data_task()
+
+ with pytest.raises(HomeAssistantError, match="AI Task error"):
+ await ai_task_entity._async_generate_data(task, chat_log)
+
+
+async def test_generate_data_with_tools(ai_task_entity) -> None:
+ """Test that tools from llm_api are bound to client."""
+ import voluptuous as vol
+
+ class MockTool:
+ name = "HassTurnOn"
+ description = "Turn on"
+ parameters = vol.Schema({vol.Required("entity_id"): str})
+
+ mock_api = MagicMock()
+ mock_api.tools = [MockTool()]
+
+ chat_log = _make_chat_log()
+ chat_log.llm_api = mock_api
+
+ bound_client = MagicMock()
+
+ async def _bound_astream(messages):
+ yield AIMessageChunk(content="Done, light is on")
+
+ bound_client.astream = MagicMock(side_effect=_bound_astream)
+ ai_task_entity.entry.runtime_data.bind_tools = MagicMock(return_value=bound_client)
+
+ task = _make_gen_data_task(instructions="Turn on kitchen light")
+
+ result = await ai_task_entity._async_generate_data(task, chat_log)
+
+ ai_task_entity.entry.runtime_data.bind_tools.assert_called_once()
+ assert result.data == "Done, light is on"
+
+
+async def test_generate_data_empty_response(ai_task_entity) -> None:
+ """Test handling of empty LLM response."""
+
+ async def _empty_astream(messages):
+ yield AIMessageChunk(content="")
+
+ ai_task_entity.entry.runtime_data.astream = MagicMock(side_effect=_empty_astream)
+
+ chat_log = _make_chat_log()
+ task = _make_gen_data_task()
+
+ result = await ai_task_entity._async_generate_data(task, chat_log)
+
+ assert result.data == ""
diff --git a/tests/test_init.py b/tests/test_init.py
index db9826f..f822888 100644
--- a/tests/test_init.py
+++ b/tests/test_init.py
@@ -210,7 +210,7 @@ async def test_handle_message_llm_error(
async def _error_stream(messages):
raise RuntimeError("API Error")
- yield # noqa: unreachable - makes this an async generator
+ yield # noqa: F841
entity.entry.runtime_data.astream = MagicMock(side_effect=_error_stream)
@@ -292,9 +292,7 @@ async def test_handle_message_builtin_recognized(
assert result.response is mock_intent_response
-async def test_supported_languages(
- hass: HomeAssistant, entity
-) -> None:
+async def test_supported_languages(hass: HomeAssistant, entity) -> None:
"""Test that supported_languages returns a list."""
languages = entity.supported_languages
assert isinstance(languages, list)
@@ -429,9 +427,11 @@ def test_ha_tool_to_dict() -> None:
class MockTool(llm.Tool):
name = "HassTurnOn"
description = "Turn on a device"
- parameters = vol.Schema({
- vol.Required("entity_id"): str,
- })
+ parameters = vol.Schema(
+ {
+ vol.Required("entity_id"): str,
+ }
+ )
async def async_call(self, hass, tool_input, llm_context):
return {"success": True}
@@ -453,7 +453,11 @@ async def _fake_astream(messages):
yield AIMessageChunk(
content="",
tool_calls=[
- {"id": "call_1", "name": "HassTurnOn", "args": {"entity_id": "light.kitchen"}},
+ {
+ "id": "call_1",
+ "name": "HassTurnOn",
+ "args": {"entity_id": "light.kitchen"},
+ },
],
)
diff --git a/tests/test_setup.py b/tests/test_setup.py
index 465da89..84e2786 100644
--- a/tests/test_setup.py
+++ b/tests/test_setup.py
@@ -1,6 +1,6 @@
"""Tests for SmartChain integration setup and unload."""
-from unittest.mock import AsyncMock, MagicMock, patch
+from unittest.mock import AsyncMock, patch
import pytest
from homeassistant.core import HomeAssistant
@@ -12,7 +12,6 @@
DOMAIN,
ID_GIGACHAT,
ID_OPENAI,
- ID_YANDEX_GPT,
)
pytestmark = pytest.mark.usefixtures("enable_custom_integrations")
From 2f894cdb73af3d7c487933aa1a47a07f6ba66197 Mon Sep 17 00:00:00 2001
From: dzerik
Date: Tue, 10 Mar 2026 18:52:32 +0300
Subject: [PATCH 24/26] docs: update all documentation for SmartChain rename
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
- Rewrote DOCUMENTATION.md with current architecture (v0.7.0)
- Replaced all GigaChain references in COMPETITIVE_ANALYSIS.md and ROADMAP.md
- Updated file paths from gigachain/ to smartchain/
- Fixed ruff format and noqa directives
🤖 Generated with Claude Code
Co-Authored-By: Claude
---
docs/COMPETITIVE_ANALYSIS.md | 14 +-
docs/DOCUMENTATION.md | 420 +++++++++++------------------------
docs/ROADMAP.md | 26 +--
3 files changed, 144 insertions(+), 316 deletions(-)
diff --git a/docs/COMPETITIVE_ANALYSIS.md b/docs/COMPETITIVE_ANALYSIS.md
index 5226c60..5726c6a 100644
--- a/docs/COMPETITIVE_ANALYSIS.md
+++ b/docs/COMPETITIVE_ANALYSIS.md
@@ -1,4 +1,4 @@
-# GigaChain — Конкурентный анализ и точки роста
+# SmartChain — Конкурентный анализ и точки роста
Дата: 2026-03-10 | Версия: 0.5.0
@@ -83,7 +83,7 @@
- **Голосовые запросы** — "Была ли активность во дворе вчера?"
- Провайдеры: OpenAI, Anthropic, Gemini, Ollama, OpenRouter, и др.
-#### GigaChain (наш, 15 stars)
+#### SmartChain (наш, 15 stars)
- GigaChat + YandexGPT + OpenAI через LangChain
- Streaming ответов
- ChatLog для истории
@@ -226,13 +226,13 @@
#### 5.1 Управление устройствами через Assist API
- **Что:** Использовать `chat_log.async_provide_llm_data()` для доступа к HA tools
-- **Зачем:** Главная фича, которую имеют ВСЕ конкуренты. Без неё GigaChain — только чат-бот, не smart home agent
+- **Зачем:** Главная фича, которую имеют ВСЕ конкуренты. Без неё SmartChain — только чат-бот, не smart home agent
- **Как:** HA LLM API предоставляет intents для управления exposed entities. Нужно передать tools в LLM и обработать tool calls
- **Сложность:** Средняя. GigaChat и DeepSeek поддерживают function calling. Паттерн задокументирован в HA developer docs
#### 5.2 AI Task entity
- **Что:** Добавить `AITaskEntity` с методом `_async_generate_data()`
-- **Зачем:** Позволит использовать GigaChain в автоматизациях, скриптах, шаблонах через `ai_task.generate_data`
+- **Зачем:** Позволит использовать SmartChain в автоматизациях, скриптах, шаблонах через `ai_task.generate_data`
- **Как:** Новый entity наряду с ConversationEntity, может разделять общую логику обработки chat_log
- **Сложность:** Низкая-средняя
@@ -279,7 +279,7 @@
- LLM анализирует тренды и прошлые события ("Какая была температура вчера?")
#### 5.10 Telegram-бот
-- Использовать GigaChain как backend для Telegram (как у YandexGPT)
+- Использовать SmartChain как backend для Telegram (как у YandexGPT)
#### 5.11 STT/TTS интеграция
- Связка с Yandex SpeechKit или GigaChat TTS для полного voice pipeline на русском
@@ -302,7 +302,7 @@
### Текущее УТП (Unique Selling Proposition)
-GigaChain — **единственная** HA интеграция, объединяющая GigaChat + YandexGPT + OpenAI в одном компоненте через LangChain. Это позволяет:
+SmartChain — **единственная** HA интеграция, объединяющая GigaChat + YandexGPT + OpenAI в одном компоненте через LangChain. Это позволяет:
- Переключаться между провайдерами без переустановки
- Использовать единый интерфейс для разных LLM
- Легко добавлять новые модели через LangChain экосистему
@@ -318,7 +318,7 @@ GigaChain — **единственная** HA интеграция, объеди
```mermaid
gantt
- title GigaChain Roadmap
+ title SmartChain Roadmap
dateFormat YYYY-MM
section Высокий приоритет
Assist API + Device Control :2026-03, 2026-04
diff --git a/docs/DOCUMENTATION.md b/docs/DOCUMENTATION.md
index 25fe8c6..62079b3 100644
--- a/docs/DOCUMENTATION.md
+++ b/docs/DOCUMENTATION.md
@@ -1,68 +1,49 @@
-# GigaChain — Техническая документация
+# SmartChain — Technical Documentation
-## Оглавление
+## Overview
-1. [Обзор проекта](#обзор-проекта)
-2. [Архитектура](#архитектура)
-3. [Структура файлов](#структура-файлов)
-4. [Поддерживаемые LLM](#поддерживаемые-llm)
-5. [Поток конфигурации](#поток-конфигурации)
-6. [Обработка диалогов](#обработка-диалогов)
-7. [Конфигурационные параметры](#конфигурационные-параметры)
-8. [Тестирование](#тестирование)
-9. [CI/CD и инструменты качества](#cicd-и-инструменты-качества)
-10. [Зависимости](#зависимости)
-11. [Changelog](#changelog)
-12. [Оставшиеся рекомендации](#оставшиеся-рекомендации)
+**SmartChain** is a custom component for [Home Assistant](https://www.home-assistant.io/) providing a voice/conversation assistant using multiple LLM providers via LangChain.
----
+- **Version:** 0.7.0
+- **Domain:** `smartchain`
+- **Integration type:** service
+- **IoT class:** cloud_polling
+- **Distribution:** [HACS](https://hacs.xyz/)
-## Обзор проекта
-
-**GigaChain** — это custom component (интеграция) для [Home Assistant](https://www.home-assistant.io/), реализующая голосового/диалогового ассистента с использованием больших языковых моделей (LLM) через фреймворк LangChain.
-
-- **Версия:** 0.5.0
-- **Тип интеграции:** service (`integration_type: "service"`)
-- **IoT-класс:** cloud_polling
-- **Распространение:** через [HACS](https://hacs.xyz/) (Home Assistant Community Store)
-- **Автор:** [@gritaro](https://github.com/gritaro)
-
----
-
-## Архитектура
-
-Интеграция реализует `ConversationEntity` из Home Assistant, что позволяет использовать LLM в качестве entity-based backend-а для голосового ассистента HA с поддержкой `ChatLog` API.
+## Architecture
```mermaid
flowchart TD
- A[Пользователь] -->|Голос / Текст| B[Home Assistant Voice Pipeline]
+ A[User] -->|Voice / Text| B[Home Assistant Voice Pipeline]
B --> C{Builtin Sentence Processor}
- C -->|Распознана команда| D[HA Intent Handler]
- C -->|Не распознана| E[GigaChainConversationEntity]
- E --> F{Выбранный LLM Engine}
+ C -->|Recognized| D[HA Intent Handler]
+ C -->|Not recognized| E[SmartChainConversationEntity]
+ E --> F{LLM Engine}
F --> G[GigaChat API]
F --> H[YandexGPT API]
F --> I[OpenAI API]
- G --> J[Ответ пользователю]
+ G --> J[Response to user]
H --> J
I --> J
D --> J
+
+ K[HA Automation] -->|ai_task.generate_data| L[SmartChainAITaskEntity]
+ L --> F
```
-### Ключевые компоненты
+### Key Components
```mermaid
classDiagram
- class GigaChainConversationEntity {
+ class SmartChainConversationEntity {
+entry: ConfigEntry
+supported_languages: list
+_async_handle_message(user_input, chat_log) ConversationResult
}
- class ConversationEntity {
- <>
- +async_process(user_input) ConversationResult
- +_async_handle_message(user_input, chat_log) ConversationResult
+ class SmartChainAITaskEntity {
+ +entry: ConfigEntry
+ +_async_generate_data(task, chat_log) GenDataTaskResult
}
class ConfigFlow {
@@ -70,12 +51,6 @@ classDiagram
+async_step_gigachat(user_input) ConfigFlowResult
+async_step_yandexgpt(user_input) ConfigFlowResult
+async_step_openai(user_input) ConfigFlowResult
- -_common_model_async_step(engine, user_input) ConfigFlowResult
- }
-
- class OptionsFlow {
- +config_entry: ConfigEntry
- +async_step_init(user_input) ConfigFlowResult
}
class client_util {
@@ -83,293 +58,146 @@ classDiagram
+get_client(hass, engine, entry, common_args)
}
- GigaChainConversationEntity --|> ConversationEntity : наследует
- GigaChainConversationEntity --> client_util : использует
- ConfigFlow --> client_util : валидация
- ConfigFlow --> OptionsFlow : создаёт
+ SmartChainConversationEntity --|> ConversationEntity
+ SmartChainAITaskEntity --|> AITaskEntity
+ SmartChainConversationEntity --> client_util
+ SmartChainAITaskEntity --> client_util
```
-### Хранение данных
-
-Клиент LLM хранится в `entry.runtime_data` (согласно best practices HA), а не в `hass.data[DOMAIN]`. Это обеспечивает автоматическую очистку при unload.
-
-### Управление историей (ChatLog)
-
-С v0.4.0 история диалогов полностью управляется нативным `ChatLog` Home Assistant. Собственный `OrderedDict` удалён. `ConversationEntity` автоматически получает `chat_log` в `_async_handle_message` — HA управляет сессиями и историей через `chat_session`.
-
-Конвертация ChatLog в LangChain messages выполняется функцией `_chatlog_to_langchain()`:
-- `SystemContent` → `SystemMessage`
-- `UserContent` → `HumanMessage`
-- `AssistantContent` → `AIMessage`
-
----
-
-## Структура файлов
+## File Structure
```
-gigachain/
+ha-smartchain/
├── custom_components/
-│ └── gigachain/
-│ ├── __init__.py # Основной модуль: setup/unload entry
-│ ├── conversation.py # ConversationEntity (основная логика агента)
-│ ├── config_flow.py # Config Flow и Options Flow для UI настройки
-│ ├── client_util.py # Фабрика LLM-клиентов и валидация подключения
-│ ├── const.py # Константы, модели, дефолтный промпт
-│ ├── manifest.json # Метаданные интеграции для HA
-│ ├── strings.json # Строки локализации (en, базовые)
+│ └── smartchain/
+│ ├── __init__.py # Entry setup/unload, platform registration
+│ ├── conversation.py # ConversationEntity (streaming, tool calling)
+│ ├── ai_task.py # AITaskEntity (data generation)
+│ ├── config_flow.py # Config Flow + Options Flow
+│ ├── client_util.py # LLM client factory + validation
+│ ├── const.py # Constants, prompts, model lists
+│ ├── manifest.json # Integration metadata
+│ ├── strings.json # Base localization strings
│ └── translations/
-│ ├── en.json # Английская локализация
-│ └── ru.json # Русская локализация
+│ ├── en.json # English localization
+│ └── ru.json # Russian localization
├── tests/
-│ ├── __init__.py # Пакет тестов
-│ ├── conftest.py # Фикстуры (hass, mock LLM client)
-│ ├── test_config_flow.py # Тесты Config Flow (11 тестов)
-│ ├── test_init.py # Тесты ConversationEntity (11 тестов)
-│ └── test_setup.py # Тесты setup/unload (4 теста)
-├── static/ # Изображения для README
-├── .github/
-│ ├── workflows/
-│ │ ├── push.yml # CI на push в main (lint + test)
-│ │ ├── pull.yml # CI на pull request (lint + test)
-│ │ └── cron.yaml # Ежедневная валидация
-│ ├── CODEOWNERS
-│ ├── settings.yml # Настройки GitHub репозитория
-│ └── dependabot.yaml # Автообновление зависимостей
+│ ├── conftest.py # Fixtures (hass, mock LLM client)
+│ ├── test_config_flow.py # Config Flow tests (11)
+│ ├── test_init.py # Conversation entity tests (19)
+│ ├── test_ai_task.py # AI Task entity tests (7)
+│ └── test_setup.py # Setup/unload tests (4)
├── docs/
-│ └── DOCUMENTATION.md # Техническая документация (этот файл)
-├── pytest.ini # Конфигурация pytest
-├── .pre-commit-config.yaml # Pre-commit hooks (ruff)
+│ ├── DOCUMENTATION.md # This file
+│ ├── COMPETITIVE_ANALYSIS.md # Competitive analysis
+│ └── ROADMAP.md # Development roadmap
+├── CLAUDE.md # Project rules for Claude Code
+├── CHANGELOG.md # Version changelog
+├── TODO.md # Task checklist
+├── README.md / README-ru.md # User documentation (EN/RU)
+├── pytest.ini # Pytest configuration
+├── requirements_test.txt # Test dependencies
├── hacs.json # HACS metadata
-├── CHANGELOG.md # Список изменений по версиям
-├── LICENSE # MIT лицензия
-├── requirements.txt # (пустой)
-├── requirements_test.txt # pytest-homeassistant-custom-component
-├── README.md # Документация (EN)
-└── README-ru.md # Документация (RU)
+└── LICENSE # MIT license
```
----
+## Supported LLM Providers
-## Поддерживаемые LLM
+| Provider | ID | Client Class | Auth Parameters |
+| ------------- | ----------- | -------------------------------------- | ------------------------ |
+| **GigaChat** | `gigachat` | `GigaChat` (langchain-gigachat) | `credentials` |
+| **YandexGPT** | `yandexgpt` | `ChatYandexGPT` (langchain-community) | `api_key` + `folder_id` |
+| **OpenAI** | `openai` | `ChatOpenAI` (langchain-openai) | `openai_api_key` |
-| Engine | ID | Статус | Класс клиента | Параметры аутентификации |
-| ------------ | ----------- | ------- | -------------------------------------- | ------------------------------ |
-| **GigaChat** | `gigachat` | Активен | `GigaChat` (langchain-gigachat) | `credentials` (auth data) |
-| **YandexGPT**| `yandexgpt` | Активен | `ChatYandexGPT` (langchain-community) | `api_key` + `folder_id` |
-| **OpenAI** | `openai` | Активен | `ChatOpenAI` (langchain-openai) | `openai_api_key` |
-
-### Доступные модели
+### Available Models
- **GigaChat:** GigaChat, GigaChat:latest, GigaChat-Plus, GigaChat-Pro, GigaChat-Max
- **YandexGPT:** YandexGPT, YandexGPT Lite, Summary
-- **OpenAI:** gpt-4o, gpt-4o-mini, gpt-4-turbo, gpt-4, gpt-3.5-turbo, o1, o1-mini, o3-mini
-
-Пользователь также может ввести произвольное имя модели в поле "Custom Model Name".
-
----
-
-## Поток конфигурации
-
-### Первоначальная настройка (Config Flow)
+- **OpenAI:** gpt-4.1, gpt-4.1-mini, gpt-4.1-nano, gpt-4o, gpt-4o-mini, o3, o3-mini, o4-mini
-```mermaid
-sequenceDiagram
- participant U as Пользователь
- participant CF as ConfigFlow
- participant CU as client_util
- participant LLM as LLM API
-
- U->>CF: async_step_user() - выбор engine
- CF->>U: Форма ввода API ключа
- U->>CF: async_step_{engine}() - ввод credentials
- CF->>CU: validate_client()
- CU->>LLM: Тестовый запрос через async_add_executor_job
- LLM-->>CU: Ответ / Ошибка
- CU-->>CF: OK / Exception
- CF->>U: Создание config entry / Показ ошибки
-```
-
-### Изменение опций (Options Flow)
-
-Пользователь может настроить:
-- Выбор модели из списка или ввод пользовательского имени модели
-- Системный промпт (шаблон Jinja2 HA)
-- Температуру генерации (0.0 - 1.0, шаг 0.05)
-- Максимум токенов
-- Использование встроенного HA командного процессора
-- Историю чата
-- Цензуру (только для GigaChat)
-- Проверку SSL (только для GigaChat)
+Custom model names are also supported.
----
-
-## Обработка диалогов
-
-### Алгоритм `_async_handle_message`
+## Conversation Flow
```mermaid
flowchart TD
- A[Входящее сообщение + ChatLog] --> B[Установить system prompt через Jinja2]
- B --> C{history enabled?}
- C -->|Да| D[Конвертировать ChatLog → LangChain messages]
- C -->|Нет| E[Создать SystemMessage + HumanMessage]
- D --> F{builtin_sentences включён?}
- E --> F
- F -->|Да| G[Отправить в HA Default Agent]
- G --> H{Распознана команда?}
- H -->|Да| I[Добавить AssistantContent в ChatLog]
- I --> J[Вернуть результат HA]
- H -->|Нет| K[Отправить в LLM через executor]
- F -->|Нет| K
- K --> L{Успешно?}
- L -->|Да| M[Добавить AssistantContent в ChatLog]
- M --> N[Вернуть ответ пользователю]
- L -->|Нет| O[Вернуть ошибку IntentResponseErrorCode.UNKNOWN]
+ A[Message + ChatLog] --> B{Assist API configured?}
+ B -->|Yes| C[async_provide_llm_data - tools + prompt]
+ B -->|No| D[Manual Jinja2 prompt + device list]
+ C --> E{Builtin sentences?}
+ D --> F{Builtin sentences enabled?}
+ F -->|Yes| G[Try HA Default Agent]
+ F -->|No| H[Build LangChain messages]
+ E --> H
+ G --> I{Recognized?}
+ I -->|Yes| J[Return HA response]
+ I -->|No| H
+ H --> K[client.astream - streaming]
+ K --> L{Tool calls?}
+ L -->|Yes| M[Execute tools via HA]
+ M --> H
+ L -->|No| N[Return response]
```
-### Управление историей
-
-История полностью управляется нативным `ChatLog` Home Assistant. При включённой опции `chat_history` весь ChatLog конвертируется в LangChain messages через `_chatlog_to_langchain()`. При отключённой — в LLM отправляются только system prompt и текущее сообщение.
+### Streaming
+Responses stream token-by-token via `ChatLog.async_add_delta_content_stream()`. The `_async_langchain_stream()` generator converts LangChain `AIMessageChunk` to HA delta dicts.
-### Streaming (v0.5.0)
+### Tool Calling (Assist API)
+When `llm_hass_api` is configured, HA tools (lights, switches, etc.) are converted to LangChain format via `_ha_tool_to_dict()` and bound to the client with `bind_tools()`. The tool calling loop runs up to `MAX_TOOL_ITERATIONS = 10` times.
-Ответы LLM передаются потоково через `ChatLog.async_add_delta_content_stream()`. Async генератор `_async_langchain_stream()` конвертирует `AIMessageChunk` от LangChain `client.astream()` в HA delta dicts (`{"role": "assistant", "content": "..."}`).
+### AI Task Entity
+`SmartChainAITaskEntity` implements `ai_task.AITaskEntity` for use in automations via `ai_task.generate_data`. Supports:
+- Plain text generation
+- Structured output (JSON parsing with `task.structure`)
+- Tool calling (same as conversation entity)
-### Системный промпт
+## Configuration Parameters
-По умолчанию промпт настраивает модель как HAL 9000 и включает информацию об устройствах и зонах Home Assistant через Jinja2-шаблоны.
+### Data (set during installation)
-Доступные переменные шаблона:
-- `ha_name` - название установки Home Assistant
-- `areas()` - список зон
-- `area_devices(area)` - устройства в зоне
-- `device_attr(device, attr)` - атрибуты устройства
+| Parameter | Key | Type | Description |
+| --------- | ----------- | ----- | ---------------------------------------- |
+| Engine | `engine` | `str` | LLM engine ID |
+| API Key | `api_key` | `str` | Authentication key |
+| Folder ID | `folder_id` | `str` | Yandex Cloud folder (YandexGPT only) |
----
+### Options (configurable after installation)
-## Конфигурационные параметры
+| Parameter | Key | Type | Default | Description |
+| ---------------------- | -------------------------- | ---------- | -------- | ------------------------------------ |
+| Model (list) | `model` | `str` | `""` | Model from provider list |
+| Model (custom) | `model_user` | `str` | `""` | Custom model name |
+| Assist API | `llm_hass_api` | `list` | - | HA LLM API for device control |
+| Prompt | `prompt` | `template` | Default | System prompt (Jinja2) |
+| Temperature | `temperature` | `float` | `0.1` | Generation temperature |
+| Max Tokens | `max_tokens` | `int` | - | Max response tokens |
+| Builtin Sentences | `process_builtin_sentences`| `bool` | `True` | Try HA builtin handler first |
+| Chat History | `chat_history` | `bool` | `True` | Keep conversation history |
+| Profanity | `profanity` | `bool` | `False` | Profanity filter (GigaChat only) |
+| Verify SSL | `verify_ssl` | `bool` | `False` | SSL cert verification (GigaChat) |
-### Данные интеграции (data) - задаются при установке
-
-| Параметр | Ключ | Тип | Описание |
-| --------- | ----------- | ----- | ----------------------------------------------- |
-| Engine | `engine` | `str` | ID LLM engine (gigachat, yandexgpt, openai) |
-| API Key | `api_key` | `str` | Ключ аутентификации |
-| Folder ID | `folder_id` | `str` | ID каталога Yandex Cloud (только YandexGPT) |
-
-### Опции (options) - настраиваются после установки
-
-| Параметр | Ключ | Тип | По умолчанию | Описание |
-| -------------------------- | -------------------------- | ---------- | --------------- | ------------------------------------------- |
-| Модель (из списка) | `model` | `str` | `""` | Модель из предложенного списка |
-| Модель (пользовательская) | `model_user` | `str` | `""` | Произвольное имя модели |
-| Промпт | `prompt` | `template` | HAL 9000 prompt | Системный промпт (Jinja2) |
-| Температура | `temperature` | `float` | `0.1` | Температура генерации |
-| Макс. токенов | `max_tokens` | `int` | - | Максимум токенов в ответе |
-| HA процессор | `process_builtin_sentences`| `bool` | `True` | Сначала пробовать встроенный HA обработчик |
-| История чата | `chat_history` | `bool` | `True` | Сохранять историю диалога |
-| Цензура | `profanity` | `bool` | `False` | Фильтр ненорматива (только GigaChat) |
-| Проверка SSL | `verify_ssl` | `bool` | `False` | Проверка SSL сертификатов (только GigaChat) |
-
----
-
-## Тестирование
-
-### Запуск тестов
+## Testing
```bash
pip install pytest-homeassistant-custom-component
python3 -m pytest tests/ -v
```
-### Покрытие (29 тестов)
-
-**`tests/test_config_flow.py`** — 11 тестов:
-- Отображение формы выбора engine (user step)
-- Выбор каждого engine → показ соответствующей формы (3 теста)
-- Полный flow для GigaChat, YandexGPT, OpenAI (3 теста)
-- Обработка ошибок: `ConnectError`, `ResponseError`, неизвестная ошибка (3 теста)
-- Skip validation (1 тест)
-
-**`tests/test_init.py`** — 14 тестов:
-- Базовый запрос к LLM через `_async_handle_message` (streaming)
-- Установка system prompt в ChatLog
-- Отправка корректных messages в LLM
-- Сохранение истории диалога (system + human + ai) через ChatLog
-- Отключение истории (`chat_history: False`)
-- Обработка ошибок LLM (graceful error response)
-- Делегирование в builtin HA agent (не распознано → LLM)
-- Делегирование в builtin HA agent (распознано → HA response)
-- `supported_languages` возвращает непустой список
-- `_attr_supports_streaming` включён
-- `_chatlog_to_langchain` конвертация (2 теста)
-- `_async_langchain_stream` конвертация чанков (2 теста)
-
-**`tests/test_setup.py`** — 4 теста:
-- Setup entry для GigaChat
-- Setup entry для OpenAI
-- Unload entry
-- Создание conversation entity при setup
-
-### Фикстуры
-
-- `setup_ha_components` (autouse) — настраивает `homeassistant` и `conversation` компоненты
-- `mock_llm_client` — мок LLM клиента с `invoke()` возвращающим `AIMessage`
-- `mock_validate_client` — мок валидации для пропуска реальных API вызовов
-- `enable_custom_integrations` — включает custom components в тестовом HA
-
----
-
-## CI/CD и инструменты качества
-
-### GitHub Actions Workflows
-
-| Workflow | Триггер | Действия |
-| ----------- | ------------ | ---------------------------------------------------------- |
-| `push.yml` | push в main | HACS + Hassfest валидация, ruff lint + format, pytest |
-| `pull.yml` | pull request | HACS + Hassfest валидация, ruff lint + format, pytest |
-| `cron.yaml` | ежедневно | HACS + Hassfest валидация |
-
-### Pre-commit hooks
-
-- **ruff** (v0.9.7) - линтер + форматирование (заменяет black, isort, flake8)
-
----
-
-## Зависимости
-
-Определены в `manifest.json`:
-
-| Зависимость | Описание |
-| -------------------------- | ---------------------------------------------- |
-| `home-assistant-intents` | Поддержка языков для conversation agent |
-| `langchain-gigachat>=0.3.0`| GigaChat LLM клиент |
-| `langchain-openai>=0.3.0` | OpenAI LLM клиент |
-| `langchain-community>=0.4.0`| YandexGPT и утилиты LangChain |
-| `yandexcloud==0.295.0` | Yandex Cloud SDK |
-
-Внутренние зависимости HA: `conversation`
-
----
-
-## Changelog
-
-Подробный список изменений по версиям — см. [CHANGELOG.md](../CHANGELOG.md).
-
-### Основные вехи
-
-- **v0.5.0** — Streaming ответов LLM через `async_add_delta_content_stream`, 29 тестов
-- **v0.4.0** — ChatLog для истории (удалён OrderedDict), миграция на langchain-gigachat/langchain-openai, pytest в CI
-- **v0.3.0** — Миграция на ConversationEntity, conversation.py, 20 тестов
-- **v0.2.1** — verify_ssl, обновление GitHub Actions, MIT лицензия
-- **v0.2.0** — Исправление блокировки event loop, удаление Anyscale, модернизация
-- **v0.1.x** — Первоначальные релизы: GigaChat, YandexGPT, OpenAI, Config/Options Flow
+### Test Coverage (41 tests)
----
+- **test_config_flow.py** — 11 tests (engine selection, full flows, error handling, skip validation)
+- **test_init.py** — 19 tests (conversation entity, streaming, tool calling, history, prompts)
+- **test_ai_task.py** — 7 tests (data generation, structured output, errors, tools)
+- **test_setup.py** — 4 tests (setup, unload, entity creation)
-## Оставшиеся рекомендации
+## Dependencies
-Все рекомендации из предыдущих версий выполнены. Возможные направления развития:
+| Package | Description |
+| -------------------------- | ------------------------------ |
+| `home-assistant-intents` | Language support |
+| `langchain-gigachat>=0.3.0`| GigaChat LLM client |
+| `langchain-openai>=0.3.0` | OpenAI LLM client |
+| `langchain-community>=0.4.0`| YandexGPT + LangChain utils |
+| `yandexcloud==0.295.0` | Yandex Cloud SDK |
-1. **LLM API интеграция** — использовать `chat_log.async_provide_llm_data()` для доступа к HA tools (управление устройствами через LLM)
-2. **Миграция ChatYandexGPT** — когда появится отдельный пакет `langchain-yandex`, мигрировать с `langchain_community`
+HA dependencies: `ai_task`, `conversation`
diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md
index d47e5a4..9d9a724 100644
--- a/docs/ROADMAP.md
+++ b/docs/ROADMAP.md
@@ -1,4 +1,4 @@
-# GigaChain — Дорожная карта развития
+# SmartChain — Дорожная карта развития
Дата: 2026-03-10 | Текущая версия: 0.6.0
@@ -30,7 +30,7 @@
```mermaid
graph TB
- subgraph "GigaChain v0.6.0"
+ subgraph "SmartChain v0.6.0"
CF[Config Flow] --> CU[client_util.py]
CU --> GC[GigaChat]
CU --> YGP[YandexGPT]
@@ -51,7 +51,7 @@ graph TB
### Разрыв с конкурентами
-| Фича | Official HA | Extended OpenAI | YandexGPT | Home-LLM | GigaChain |
+| Фича | Official HA | Extended OpenAI | YandexGPT | Home-LLM | SmartChain |
|-------|:-----------:|:---------------:|:---------:|:--------:|:---------:|
| Assist API / Device Control | + | + | + | + | **+ (v0.6)** |
| AI Task entity | + | - | - | + | - |
@@ -80,18 +80,18 @@ graph TB
**Что:**
- Добавить `AITaskEntity` с методом `_async_generate_data(task, chat_log)`
-- Позволяет использовать GigaChain в автоматизациях HA через `ai_task.generate_data`
+- Позволяет использовать SmartChain в автоматизациях HA через `ai_task.generate_data`
- Примеры: "Составь план уборки на основе загрязнённости комнат", "Проанализируй расход электричества за неделю"
**Файлы:**
-- `custom_components/gigachain/ai_task.py` — новый файл с `GigaChainAITaskEntity`
-- `custom_components/gigachain/__init__.py` — добавить `Platform.AI_TASK`
-- `custom_components/gigachain/manifest.json` — добавить `"ai_task"` в dependencies
+- `custom_components/smartchain/ai_task.py` — новый файл с `SmartChainAITaskEntity`
+- `custom_components/smartchain/__init__.py` — добавить `Platform.AI_TASK`
+- `custom_components/smartchain/manifest.json` — добавить `"ai_task"` в dependencies
- `tests/test_ai_task.py` — тесты
**Реализация:**
```python
-class GigaChainAITaskEntity(AITaskEntity):
+class SmartChainAITaskEntity(AITaskEntity):
async def _async_generate_data(
self, task: ai_task.GenData, chat_log: ChatLog
) -> None:
@@ -143,7 +143,7 @@ class GigaChainAITaskEntity(AITaskEntity):
#### 0.8.3 — Anthropic (Claude)
-Для пользователей, которые хотят Claude через GigaChain.
+Для пользователей, которые хотят Claude через SmartChain.
**Файлы:**
- `const.py` — `ID_ANTHROPIC`, модели (`claude-sonnet-4-6`, `claude-haiku-4-5`)
@@ -206,7 +206,7 @@ class GigaChainAITaskEntity(AITaskEntity):
**Что:**
- GigaChat 2.0 имеет встроенную генерацию через Kandinsky
- YandexGPT имеет YandexART API
-- Результат: `image` entity или сервис `gigachain.generate_image`
+- Результат: `image` entity или сервис `smartchain.generate_image`
**Реализация:**
- Для GigaChat: уже поддерживается через API (модель сама решает, когда генерировать)
@@ -273,7 +273,7 @@ class GigaChainAITaskEntity(AITaskEntity):
**Сложность:** Низкая
**Что:**
-- Использование GigaChain как backend для Telegram-бота
+- Использование SmartChain как backend для Telegram-бота
- Управление домом через Telegram
- Отправка уведомлений с анализом камер
@@ -287,7 +287,7 @@ class GigaChainAITaskEntity(AITaskEntity):
**Что:**
- Связка с Yandex SpeechKit для STT/TTS на русском
- GigaChat TTS (когда появится)
-- Полный voice pipeline: микрофон → STT → GigaChain → TTS → динамик
+- Полный voice pipeline: микрофон → STT → SmartChain → TTS → динамик
---
@@ -348,7 +348,7 @@ class GigaChainAITaskEntity(AITaskEntity):
```mermaid
gantt
- title GigaChain Roadmap 2026
+ title SmartChain Roadmap 2026
dateFormat YYYY-MM
axisFormat %b %Y
From 51c3a4ef1f61f6682a5f6f94176ff54ebbfe6959 Mon Sep 17 00:00:00 2001
From: dzerik
Date: Tue, 10 Mar 2026 18:54:53 +0300
Subject: [PATCH 25/26] build: migrate to uv + pyproject.toml
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Replace pytest.ini with pyproject.toml configuration.
Update CI workflows to use astral-sh/setup-uv for dependency management.
🤖 Generated with Claude Code
Co-Authored-By: Claude
---
.github/workflows/pull.yml | 19 ++++++-------------
.github/workflows/push.yml | 19 ++++++-------------
pyproject.toml | 26 ++++++++++++++++++++++++++
pytest.ini | 2 --
4 files changed, 38 insertions(+), 28 deletions(-)
create mode 100644 pyproject.toml
delete mode 100644 pytest.ini
diff --git a/.github/workflows/pull.yml b/.github/workflows/pull.yml
index c6ce798..f84e2cc 100644
--- a/.github/workflows/pull.yml
+++ b/.github/workflows/pull.yml
@@ -26,22 +26,15 @@ jobs:
name: Lint with ruff
steps:
- uses: "actions/checkout@v4"
- - uses: "actions/setup-python@v5"
- with:
- python-version: ${{ env.PYTHON_VERSION }}
- - run: python3 -m pip install ruff
- - run: ruff check .
- - run: ruff format --check .
+ - uses: "astral-sh/setup-uv@v5"
+ - run: uv run ruff check .
+ - run: uv run ruff format --check .
test:
runs-on: "ubuntu-latest"
name: Run tests
steps:
- uses: "actions/checkout@v4"
- - uses: "actions/setup-python@v5"
- with:
- python-version: ${{ env.PYTHON_VERSION }}
- - run: |
- python3 -m pip install -r requirements_test.txt
- python3 -m pip install langchain-core gigachat
- - run: python3 -m pytest tests/ -v
+ - uses: "astral-sh/setup-uv@v5"
+ - run: uv sync
+ - run: uv run pytest tests/ -v
diff --git a/.github/workflows/push.yml b/.github/workflows/push.yml
index 1957b62..5b743ff 100644
--- a/.github/workflows/push.yml
+++ b/.github/workflows/push.yml
@@ -30,22 +30,15 @@ jobs:
name: Lint with ruff
steps:
- uses: "actions/checkout@v4"
- - uses: "actions/setup-python@v5"
- with:
- python-version: ${{ env.PYTHON_VERSION }}
- - run: python3 -m pip install ruff
- - run: ruff check .
- - run: ruff format --check .
+ - uses: "astral-sh/setup-uv@v5"
+ - run: uv run ruff check .
+ - run: uv run ruff format --check .
test:
runs-on: "ubuntu-latest"
name: Run tests
steps:
- uses: "actions/checkout@v4"
- - uses: "actions/setup-python@v5"
- with:
- python-version: ${{ env.PYTHON_VERSION }}
- - run: |
- python3 -m pip install -r requirements_test.txt
- python3 -m pip install langchain-core gigachat
- - run: python3 -m pytest tests/ -v
+ - uses: "astral-sh/setup-uv@v5"
+ - run: uv sync
+ - run: uv run pytest tests/ -v
diff --git a/pyproject.toml b/pyproject.toml
new file mode 100644
index 0000000..5d4e4fc
--- /dev/null
+++ b/pyproject.toml
@@ -0,0 +1,26 @@
+[project]
+name = "ha-smartchain"
+version = "0.7.0"
+description = "SmartChain — multi-provider LLM conversation agent for Home Assistant"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.12"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+
+[tool.ruff]
+target-version = "py312"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP"]
+
+[dependency-groups]
+dev = [
+ "pytest-homeassistant-custom-component>=0.13",
+ "ruff>=0.15",
+ "langchain-core>=0.3",
+ "gigachat>=0.1",
+ "PyTurboJPEG>=2.0",
+]
diff --git a/pytest.ini b/pytest.ini
deleted file mode 100644
index 2f4c80e..0000000
--- a/pytest.ini
+++ /dev/null
@@ -1,2 +0,0 @@
-[pytest]
-asyncio_mode = auto
From 30e3c5d71f6b6e8d9c08e822d35c4728a22b5b02 Mon Sep 17 00:00:00 2001
From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com>
Date: Tue, 10 Mar 2026 15:55:54 +0000
Subject: [PATCH 26/26] Bump actions/checkout from 4 to 6
Bumps [actions/checkout](https://github.com/actions/checkout) from 4 to 6.
- [Release notes](https://github.com/actions/checkout/releases)
- [Changelog](https://github.com/actions/checkout/blob/main/CHANGELOG.md)
- [Commits](https://github.com/actions/checkout/compare/v4...v6)
---
updated-dependencies:
- dependency-name: actions/checkout
dependency-version: '6'
dependency-type: direct:production
update-type: version-update:semver-major
...
Signed-off-by: dependabot[bot]
---
.github/workflows/cron.yaml | 2 +-
.github/workflows/pull.yml | 6 +++---
.github/workflows/push.yml | 6 +++---
3 files changed, 7 insertions(+), 7 deletions(-)
diff --git a/.github/workflows/cron.yaml b/.github/workflows/cron.yaml
index a58519a..85030c2 100644
--- a/.github/workflows/cron.yaml
+++ b/.github/workflows/cron.yaml
@@ -9,7 +9,7 @@ jobs:
runs-on: "ubuntu-latest"
name: Validate
steps:
- - uses: "actions/checkout@v4"
+ - uses: "actions/checkout@v6"
- name: HACS validation
uses: "hacs/action@main"
diff --git a/.github/workflows/pull.yml b/.github/workflows/pull.yml
index f84e2cc..b3eb8ba 100644
--- a/.github/workflows/pull.yml
+++ b/.github/workflows/pull.yml
@@ -11,7 +11,7 @@ jobs:
runs-on: "ubuntu-latest"
name: Validate
steps:
- - uses: "actions/checkout@v4"
+ - uses: "actions/checkout@v6"
- name: HACS validation
uses: "hacs/action@main"
@@ -25,7 +25,7 @@ jobs:
runs-on: "ubuntu-latest"
name: Lint with ruff
steps:
- - uses: "actions/checkout@v4"
+ - uses: "actions/checkout@v6"
- uses: "astral-sh/setup-uv@v5"
- run: uv run ruff check .
- run: uv run ruff format --check .
@@ -34,7 +34,7 @@ jobs:
runs-on: "ubuntu-latest"
name: Run tests
steps:
- - uses: "actions/checkout@v4"
+ - uses: "actions/checkout@v6"
- uses: "astral-sh/setup-uv@v5"
- run: uv sync
- run: uv run pytest tests/ -v
diff --git a/.github/workflows/push.yml b/.github/workflows/push.yml
index 5b743ff..044b124 100644
--- a/.github/workflows/push.yml
+++ b/.github/workflows/push.yml
@@ -14,7 +14,7 @@ jobs:
runs-on: "ubuntu-latest"
name: Validate
steps:
- - uses: "actions/checkout@v4"
+ - uses: "actions/checkout@v6"
- name: HACS validation
uses: "hacs/action@main"
@@ -29,7 +29,7 @@ jobs:
runs-on: "ubuntu-latest"
name: Lint with ruff
steps:
- - uses: "actions/checkout@v4"
+ - uses: "actions/checkout@v6"
- uses: "astral-sh/setup-uv@v5"
- run: uv run ruff check .
- run: uv run ruff format --check .
@@ -38,7 +38,7 @@ jobs:
runs-on: "ubuntu-latest"
name: Run tests
steps:
- - uses: "actions/checkout@v4"
+ - uses: "actions/checkout@v6"
- uses: "astral-sh/setup-uv@v5"
- run: uv sync
- run: uv run pytest tests/ -v
-
+[](https://github.com/gritaro/ha-smartchain/blob/main/README.md)
+[](https://github.com/gritaro/ha-smartchain/blob/main/README-ru.md)
- 🦜️🔗 GigaChain (GigaChat + LangChain)
+
+
-# GigaChain integration with Home Assistant
-[](https://hacs.xyz)
-[](https://github.com/gritaro/gigachain/actions/workflows/hacs.yaml)
-[](https://github.com/gritaro/gigachain/actions/workflows/hassfest.yaml)
-[](https://github.com/gritaro/gigachain)
-[](https://github.com/gritaro/gigachain/releases/latest)
-[](https://github.com/gritaro/gigachain/releases)
-
-This integration implements Voice Assistant for Home Assistant using GigaChain framework.
-Currently supported LMMs:
-* [GigaChat](#GigaChat) (Sber LLM)
-* [YandexGPT](#YandexGPT)
-* [OpenAI](#OpenAI) aka ChatGPT (not tested)
-* [~~Anyscale~~](#Anyscale)
-
-## Installation
-Install it like any other HACS integration.
-
-### Requirements
-Home Assistant with installed [HACS](https://hacs.xyz/)
-
-### Installation with HACS
-Find GigaChain in HACS store. If you can't find it in store, you could [add this url as HACS custom repository](https://hacs.xyz/docs/faq/custom_repositories).
-
-[](https://github.com/gritaro/gigachain)
+[](https://hacs.xyz)
+[](https://github.com/gritaro/ha-smartchain/releases)
-Restart Home Assistant.
+## Overview
-## Add Integration
+SmartChain is a Home Assistant custom integration that provides a voice/conversation assistant powered by multiple LLM providers through LangChain:
-[](https://my.home-assistant.io/redirect/brand/?brand=+GigaChain)
+- **GigaChat** (Sber) — Russian-focused LLM
+- **YandexGPT** — Yandex Cloud LLM
+- **OpenAI** — GPT-4.1, GPT-4o, o3, o4-mini
+### Key Features
-After adding, configure integration.
+- **Streaming responses** — real-time token-by-token output
+- **Assist API (tool calling)** — control HA devices via LLM (lights, switches, locks, etc.)
+- **Chat history** — multi-turn conversations with context
+- **Builtin HA sentence processing** — fallback to native HA commands
+- **Customizable system prompt** — Jinja2 templates with device/area context
+- **Multiple LLM providers** — switch providers without losing configuration
-## Settings
-### GigaChat
-### GigaChat Authorization
-You need to register at https://developers.sber.ru/studio and get an "authorization data" key.
-
-> [!NOTE]
-> You can find more details in GigaChat [official documentation](https://developers.sber.ru/docs/en/gigachat/api/integration).
->
-
-SmartChain
+Multi-provider LLM conversation agent for Home Assistant
-
-### YandexGPT
-Quick start
-
-Create service account with role `ai.languageModels.user`.
-Create API key.
-You can find Folder ID using this link.
+## Installation
-### OpenAI
-Create API key here https://platform.openai.com/account/api-keys
+### Requirements
+- Home Assistant with [HACS](https://hacs.xyz/) installed
-### ~~Anyscale~~
-[~~Register account~~](https://app.endpoints.anyscale.com/welcome) ~~and create API key~~ [~~here~~](https://app.endpoints.anyscale.com/credentials)
-Not supported anymore.
+### Install via HACS
+1. Add this repository as a [custom HACS repository](https://hacs.xyz/docs/faq/custom_repositories)
+2. Search for "SmartChain" in HACS
+3. Install and restart Home Assistant
## Configuration
-* _Prompt template_ (template, Home Assistant `template`)
-
-The starting text for the AI language model to generate new text from.
-This text can include information about your Home Assistant instance, devices, and areas and is written using [Home Assistant Templating](https://www.home-assistant.io/docs/configuration/templating/).
-Default value comes from official integration OpenAI Conversation
-
-* _Model_ (model, `string`)
-
-Language model is used for text generation
+### 1. Add Integration
+Go to **Settings → Devices & Services → Add Integration → SmartChain**
-* _Temperature_ (temperature, `float`)
+### 2. Select LLM Provider
+Choose GigaChat, YandexGPT, or OpenAI and provide API credentials.
-A value that determines the level of creativity and risk-taking the model should use when generating text.
-A higher temperature means the model is more likely to generate unexpected results, while a lower temperature results in more deterministic results.
-
-* Max Tokens (max_tokens, `int`)
+### 3. Configure Options
+- **Model** — select or type custom model name
+- **Assist API** — enable device control via LLM tool calling
+- **System Prompt** — customize the assistant's behavior (Jinja2 template)
+- **Temperature** — control response creativity (0.0–1.0)
+- **Max Tokens** — limit response length
+- **Chat History** — enable/disable multi-turn memory
+- **Builtin Sentences** — use HA's native command processor as fallback
-The maximum number of words or “tokens” that the AI model should generate in its completion of the prompt.
+### Provider Setup
-* _Process HA Builtin Sentences_ (process_builtin_sentences, `bool`)
+#### GigaChat
+Register at [developers.sber.ru](https://developers.sber.ru/studio) and get authorization credentials.
-If enabled, integration first will pass all sentences to [HA built-in sentence processor](https://www.home-assistant.io/voice_control/builtin_sentences).
-This is default behaviour of default Home Assistant Voice Assistant engine which allow you to use commands something like `turn on the living room light`.
-If sentence will not be recognized by HA, it will be passed further to chosen LLM.
+#### YandexGPT
+Create a [service account](https://cloud.yandex.com/en/docs/iam/operations/sa/create) with `ai.languageModels.user` role and generate an [API key](https://cloud.yandex.com/en/docs/iam/operations/api-key/create).
-* Chat History (chat_history, `bool`)
+#### OpenAI
+Get an API key at [platform.openai.com](https://platform.openai.com/account/api-keys)
-Keep all conversation history.
+## Usage
+Create a Voice Assistant in HA settings and select your SmartChain entity as the conversation agent.
-## Using as Voice Assistant
-Create and configure Voice Assistant:
+## License
-
+MIT
diff --git a/TODO.md b/TODO.md
new file mode 100644
index 0000000..44affd5
--- /dev/null
+++ b/TODO.md
@@ -0,0 +1,32 @@
+# SmartChain — TODO
+
+## Phase 1 — Competitive parity
+
+- [x] v0.6 Assist API — device control via tool calling
+- [x] v0.7 Rename GigaChain -> SmartChain + AI Task entity
+- [ ] v0.8.1 Ollama — local models (T-Pro, Qwen, Llama, Home-3B)
+- [ ] v0.8.2 DeepSeek — cheapest cloud provider
+- [ ] v0.8.3 Anthropic — Claude via LangChain
+- [ ] v0.9 Sub-entries — multiple agents with different models/prompts
+
+## Phase 2 — Differentiation
+
+- [ ] v1.0 Vision — camera image analysis (GigaChat 2.0, GPT-4o, Ollama)
+- [ ] v1.1 Image generation — Kandinsky (GigaChat) + YandexART
+- [ ] v1.2 MCP — connect external MCP servers as tools
+- [ ] v1.3 State history — LLM analyzes past events and trends
+
+## Phase 3 — Leadership
+
+- [ ] v1.4 Multi-agent — Dispatcher + specialized agents (LangGraph)
+- [ ] v1.5 Telegram bot — home control via Telegram
+- [ ] v1.6 STT/TTS — Yandex SpeechKit, full voice pipeline
+- [ ] v1.7 Skill system — loadable skills from YAML
+- [ ] v1.8 Prompt caching — token savings on repeated requests
+
+## Technical debt
+
+- [ ] Tests: Options Flow (config_flow)
+- [ ] Test: integration with real ChatLog (not mock)
+- [ ] E2E test: tool calling loop
+- [ ] HACS: verify compatibility and publish
diff --git a/custom_components/gigachain/conversation.py b/custom_components/gigachain/conversation.py
deleted file mode 100644
index 6b5cee9..0000000
--- a/custom_components/gigachain/conversation.py
+++ /dev/null
@@ -1,172 +0,0 @@
-"""Conversation entity for GigaChain integration."""
-
-import logging
-from collections.abc import AsyncIterable
-from typing import Any, Literal
-
-from home_assistant_intents import get_languages
-from homeassistant.components.conversation import (
- ChatLog,
- ConversationEntity,
- ConversationInput,
- ConversationResult,
-)
-from homeassistant.components.conversation.chat_log import (
- AssistantContent,
- SystemContent,
- UserContent,
-)
-from homeassistant.config_entries import ConfigEntry
-from homeassistant.helpers import intent, template
-from homeassistant.helpers.entity_platform import AddEntitiesCallback
-from langchain_core.messages import (
- AIMessage,
- BaseMessage,
- HumanMessage,
- SystemMessage,
-)
-
-from .const import (
- CONF_CHAT_HISTORY,
- CONF_PROCESS_BUILTIN_SENTENCES,
- CONF_PROMPT,
- DEFAULT_CHAT_HISTORY,
- DEFAULT_PROCESS_BUILTIN_SENTENCES,
- DEFAULT_PROMPT,
-)
-
-LOGGER = logging.getLogger(__name__)
-
-
-async def async_setup_entry(
- hass,
- config_entry: ConfigEntry,
- async_add_entities: AddEntitiesCallback,
-) -> None:
- """Set up conversation entity."""
- async_add_entities([GigaChainConversationEntity(config_entry)])
-
-
-class GigaChainConversationEntity(ConversationEntity):
- """GigaChain conversation entity using ConversationEntity API."""
-
- _attr_has_entity_name = True
- _attr_name = None
- _attr_supports_streaming = True
-
- def __init__(self, entry: ConfigEntry) -> None:
- """Initialize the entity."""
- self.entry = entry
- self._attr_unique_id = entry.entry_id
-
- @property
- def supported_languages(self) -> list[str] | Literal["*"]:
- """Return a list of supported languages."""
- return get_languages()
-
- async def _async_handle_message(
- self,
- user_input: ConversationInput,
- chat_log: ChatLog,
- ) -> ConversationResult:
- """Handle a conversation message via ChatLog API."""
- conversation_id = chat_log.conversation_id
-
- # Generate system prompt
- raw_prompt = self.entry.options.get(CONF_PROMPT, DEFAULT_PROMPT)
- prompt = template.Template(raw_prompt, self.hass).async_render(
- {"ha_name": self.hass.config.location_name},
- parse_result=False,
- )
- chat_log.content[0] = SystemContent(content=prompt)
-
- # Convert ChatLog content → LangChain messages for LLM
- chat_history_enabled = self.entry.options.get(
- CONF_CHAT_HISTORY, DEFAULT_CHAT_HISTORY
- )
- if chat_history_enabled:
- messages = _chatlog_to_langchain(chat_log)
- else:
- # Without history: only system prompt + current user message
- messages = [
- SystemMessage(content=prompt),
- HumanMessage(content=user_input.text),
- ]
-
- # Try builtin HA sentence processor first
- use_builtin = self.entry.options.get(
- CONF_PROCESS_BUILTIN_SENTENCES, DEFAULT_PROCESS_BUILTIN_SENTENCES
- )
- if use_builtin:
- from homeassistant.components.conversation import agent_manager
-
- default_agent = agent_manager.async_get_agent(self.hass, None)
- default_response = await default_agent.async_process(user_input)
-
- if default_response.response.intent:
- speech = (
- default_response.response.speech.get("plain", {}).get("speech", "")
- )
- chat_log.async_add_assistant_content_without_tools(
- AssistantContent(
- agent_id=user_input.agent_id,
- content=speech,
- )
- )
- return default_response
-
- # Call LLM with streaming
- client = self.entry.runtime_data
-
- try:
- async for _content in chat_log.async_add_delta_content_stream(
- user_input.agent_id,
- _async_langchain_stream(client, messages),
- ):
- pass
- except Exception as err:
- LOGGER.exception("Unexpected exception %s", type(err))
- response = intent.IntentResponse(language=user_input.language)
- response.async_set_error(
- intent.IntentResponseErrorCode.UNKNOWN,
- f"Houston we have a problem: {err}",
- )
- return ConversationResult(
- conversation_id=conversation_id, response=response
- )
-
- response = intent.IntentResponse(language=user_input.language)
- response.async_set_speech(chat_log.content[-1].content or "")
- return ConversationResult(
- conversation_id=conversation_id, response=response
- )
-
-
-def _chatlog_to_langchain(chat_log: ChatLog) -> list[BaseMessage]:
- """Convert ChatLog content to LangChain message list."""
- messages: list[BaseMessage] = []
- for content in chat_log.content:
- if isinstance(content, SystemContent):
- messages.append(SystemMessage(content=content.content))
- elif isinstance(content, UserContent):
- messages.append(HumanMessage(content=content.content))
- elif isinstance(content, AssistantContent):
- if content.content:
- messages.append(AIMessage(content=content.content))
- return messages
-
-
-async def _async_langchain_stream(
- client: Any, messages: list[BaseMessage]
-) -> AsyncIterable[dict[str, Any]]:
- """Convert LangChain astream chunks to HA delta dicts."""
- first = True
- async for chunk in client.astream(messages):
- delta: dict[str, Any] = {}
- if first:
- delta["role"] = "assistant"
- first = False
- if chunk.content:
- delta["content"] = chunk.content
- if delta:
- yield delta
diff --git a/custom_components/gigachain/__init__.py b/custom_components/smartchain/__init__.py
similarity index 94%
rename from custom_components/gigachain/__init__.py
rename to custom_components/smartchain/__init__.py
index b47c502..47d914b 100644
--- a/custom_components/gigachain/__init__.py
+++ b/custom_components/smartchain/__init__.py
@@ -1,4 +1,4 @@
-"""The GigaChain integration."""
+"""The SmartChain integration."""
import logging
@@ -28,7 +28,7 @@ async def update_listener(hass: HomeAssistant, entry: ConfigEntry) -> None:
async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
- """Initialize GigaChain."""
+ """Initialize SmartChain."""
engine = entry.data.get(CONF_ENGINE) or ID_GIGACHAT
model = entry.options.get(CONF_CHAT_MODEL_USER)
if not model or not model.strip():
@@ -56,5 +56,5 @@ async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
async def async_unload_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
- """Unload GigaChain."""
+ """Unload SmartChain."""
return await hass.config_entries.async_unload_platforms(entry, PLATFORMS)
diff --git a/custom_components/smartchain/ai_task.py b/custom_components/smartchain/ai_task.py
new file mode 100644
index 0000000..52d87ed
--- /dev/null
+++ b/custom_components/smartchain/ai_task.py
@@ -0,0 +1,95 @@
+"""AI Task entity for SmartChain integration."""
+
+import logging
+from typing import Any
+
+from homeassistant.components import ai_task, conversation
+from homeassistant.config_entries import ConfigEntry
+from homeassistant.exceptions import HomeAssistantError
+from homeassistant.helpers.entity_platform import AddEntitiesCallback
+
+from .const import MAX_TOOL_ITERATIONS
+from .conversation import _async_langchain_stream, _chatlog_to_langchain, _ha_tool_to_dict
+
+LOGGER = logging.getLogger(__name__)
+
+
+async def async_setup_entry(
+ hass,
+ config_entry: ConfigEntry,
+ async_add_entities: AddEntitiesCallback,
+) -> None:
+ """Set up AI Task entity."""
+ async_add_entities([SmartChainAITaskEntity(config_entry)])
+
+
+class SmartChainAITaskEntity(ai_task.AITaskEntity):
+ """SmartChain AI Task entity for data generation."""
+
+ _attr_has_entity_name = True
+ _attr_name = None
+
+ def __init__(self, entry: ConfigEntry) -> None:
+ """Initialize the entity."""
+ self.entry = entry
+ self._attr_unique_id = f"{entry.entry_id}_ai_task"
+ self._attr_supported_features = ai_task.AITaskEntityFeature.GENERATE_DATA
+
+ async def _async_generate_data(
+ self,
+ task: ai_task.GenDataTask,
+ chat_log: conversation.ChatLog,
+ ) -> ai_task.GenDataTaskResult:
+ """Handle a generate data task."""
+ client = self.entry.runtime_data
+ tools: list[dict[str, Any]] = (
+ [_ha_tool_to_dict(tool) for tool in chat_log.llm_api.tools]
+ if chat_log.llm_api
+ else []
+ )
+ bound_client = client.bind_tools(tools) if tools else client
+
+ for _iteration in range(MAX_TOOL_ITERATIONS):
+ messages = _chatlog_to_langchain(chat_log)
+
+ try:
+ async for _content in chat_log.async_add_delta_content_stream(
+ self.entity_id,
+ _async_langchain_stream(bound_client, messages),
+ ):
+ pass
+ except Exception as err:
+ LOGGER.exception("AI Task error: %s", type(err))
+ raise HomeAssistantError(f"AI Task error: {err}") from err
+
+ if not chat_log.unresponded_tool_results:
+ break
+
+ if not isinstance(chat_log.content[-1], conversation.AssistantContent):
+ raise HomeAssistantError(
+ "Last content in chat log is not an AssistantContent"
+ )
+
+ text = chat_log.content[-1].content or ""
+
+ if task.structure:
+ from homeassistant.util.json import json_loads
+ from json import JSONDecodeError
+
+ try:
+ data = json_loads(text)
+ except JSONDecodeError as err:
+ LOGGER.error("Failed to parse structured response: %s", err)
+ raise HomeAssistantError(
+ "Failed to parse structured AI Task response"
+ ) from err
+
+ return ai_task.GenDataTaskResult(
+ conversation_id=chat_log.conversation_id,
+ data=data,
+ )
+
+ return ai_task.GenDataTaskResult(
+ conversation_id=chat_log.conversation_id,
+ data=text,
+ )
diff --git a/custom_components/gigachain/client_util.py b/custom_components/smartchain/client_util.py
similarity index 100%
rename from custom_components/gigachain/client_util.py
rename to custom_components/smartchain/client_util.py
diff --git a/custom_components/gigachain/config_flow.py b/custom_components/smartchain/config_flow.py
similarity index 87%
rename from custom_components/gigachain/config_flow.py
rename to custom_components/smartchain/config_flow.py
index b47d1ae..93a2df5 100644
--- a/custom_components/gigachain/config_flow.py
+++ b/custom_components/smartchain/config_flow.py
@@ -1,4 +1,4 @@
-"""Config flow for GigaChain integration."""
+"""Config flow for SmartChain integration."""
from __future__ import annotations
@@ -18,12 +18,14 @@
TemplateSelector)
from httpx import ConnectError
+from homeassistant.helpers import llm
+
from .client_util import validate_client
from .const import (CONF_API_KEY, CONF_CHAT_MODEL, CONF_CHAT_MODEL_USER,
CONF_ENGINE, CONF_ENGINE_OPTIONS, CONF_FOLDER_ID,
- CONF_MAX_TOKENS, CONF_PROFANITY, CONF_PROMPT,
- CONF_SKIP_VALIDATION, CONF_TEMPERATURE, CONF_VERIFY_SSL,
- DEFAULT_CHAT_MODEL, DEFAULT_VERIFY_SSL,
+ CONF_LLM_HASS_API, CONF_MAX_TOKENS, CONF_PROFANITY,
+ CONF_PROMPT, CONF_SKIP_VALIDATION, CONF_TEMPERATURE,
+ CONF_VERIFY_SSL, DEFAULT_CHAT_MODEL, DEFAULT_VERIFY_SSL,
ENGINE_MODELS, DEFAULT_PROFANITY, DEFAULT_PROMPT,
DEFAULT_SKIP_VALIDATION, DEFAULT_TEMPERATURE, DOMAIN,
ID_GIGACHAT, ID_OPENAI, ID_YANDEX_GPT, UNIQUE_ID,
@@ -75,7 +77,7 @@
class ConfigFlow(config_entries.ConfigFlow, domain=DOMAIN):
- """Handle a config flow for GigaChain."""
+ """Handle a config flow for SmartChain."""
VERSION = 1
@@ -146,7 +148,7 @@ def async_get_options_flow(
class OptionsFlow(config_entries.OptionsFlow):
- """GigaChain config flow options handler."""
+ """SmartChain config flow options handler."""
def __init__(self, config_entry: config_entries.ConfigEntry) -> None:
"""Initialize options flow."""
@@ -158,7 +160,7 @@ async def async_step_init(
"""Manage the options."""
unique_id = self.config_entry.unique_id
schema = common_config_option_schema(
- unique_id, self.config_entry.options
+ self.hass, unique_id, self.config_entry.options
)
if user_input is not None:
model = user_input.get(CONF_CHAT_MODEL_USER)
@@ -170,6 +172,10 @@ async def async_step_init(
errors={"base": "model_required"},
)
+ # Remove empty LLM API selection
+ if not user_input.get(CONF_LLM_HASS_API):
+ user_input.pop(CONF_LLM_HASS_API, None)
+
return self.async_create_entry(title=unique_id, data=user_input)
return self.async_show_form(
@@ -179,11 +185,17 @@ async def async_step_init(
def common_config_option_schema(
- unique_id: str, options: MappingProxyType[str, Any]
+ hass, unique_id: str, options: MappingProxyType[str, Any]
) -> vol.Schema:
- """Return a schema for GigaChain completion options."""
+ """Return a schema for SmartChain completion options."""
if not options:
options = DEFAULT_OPTIONS
+
+ hass_apis: list[selector.SelectOptionDict] = [
+ selector.SelectOptionDict(value=api.id, label=api.name)
+ for api in llm.async_get_apis(hass)
+ ]
+
schema = vol.Schema({
vol.Optional(
CONF_CHAT_MODEL,
@@ -200,9 +212,16 @@ def common_config_option_schema(
"suggested_value": options.get(CONF_CHAT_MODEL_USER)
},
): str,
+ vol.Optional(
+ CONF_LLM_HASS_API,
+ ): selector.SelectSelector(
+ selector.SelectSelectorConfig(
+ options=hass_apis, multiple=True, mode=SelectSelectorMode("dropdown")
+ ),
+ ),
vol.Optional(
CONF_PROMPT,
- description={"suggested_value": options[CONF_PROMPT]},
+ description={"suggested_value": options.get(CONF_PROMPT, DEFAULT_PROMPT)},
default=DEFAULT_PROMPT,
): TemplateSelector(),
vol.Optional(
diff --git a/custom_components/gigachain/const.py b/custom_components/smartchain/const.py
similarity index 66%
rename from custom_components/gigachain/const.py
rename to custom_components/smartchain/const.py
index 3328385..3ab1be7 100644
--- a/custom_components/gigachain/const.py
+++ b/custom_components/smartchain/const.py
@@ -1,8 +1,8 @@
-"""Constants for the GigaChain integration."""
+"""Constants for the SmartChain integration."""
from homeassistant.helpers import selector
-DOMAIN = "gigachain"
+DOMAIN = "smartchain"
CONF_ENGINE = "engine"
CONF_CHAT_MODEL = "model"
CONF_CHAT_MODEL_USER = "model_user"
@@ -21,9 +21,12 @@
CONF_CHAT_HISTORY = "chat_history"
DEFAULT_CHAT_HISTORY = True
CONF_PROMPT = "prompt"
-DEFAULT_PROMPT = """Ты HAL 9000, компьютер из цикла произведений «Космическая одиссея» Артура Кларка, обладающий способностью к самообучению.
-Мы находимся в умном доме под управлением системы Home Assistant.
-В доме есть следующие помещения и устройства:
+DEFAULT_PROMPT = """You are a smart home voice assistant {{ ha_name }} powered by Home Assistant.
+Answer truthfully and to the point. Answer in plain text, briefly and clearly.
+Answer in the user's language."""
+
+DEFAULT_DEVICES_PROMPT = """
+The following rooms, devices and sensors are available in the home:
{%- for area in areas() %}
{%- set area_info = namespace(printed=false) %}
{%- for device in area_devices(area) -%}
@@ -34,11 +37,20 @@
{%- set area_info.printed = true %}
{%- endif %}
- {{ device_attr(device, "name") }}{% if device_attr(device, "model") and (device_attr(device, "model") | string) not in (device_attr(device, "name") | string) %} ({{ device_attr(device, "model") }}){% endif %}
+
+ {%- for entity_id in device_entities(device) %}
+ {%- set entity_domain = entity_id.split('.')[0] %}
+ {%- set dc = state_attr(entity_id, 'device_class') %}
+ {%- set friendly = state_attr(entity_id, 'friendly_name') %}
+ {%- set entity_state = states(entity_id) %}
+ {%- if entity_state and entity_state != 'unavailable' %}
+ - {{ entity_id }} ({{ entity_domain }}{% if dc %}, {{ dc }}{% endif %}): {{ entity_state }}{% if state_attr(entity_id, 'unit_of_measurement') %} {{ state_attr(entity_id, 'unit_of_measurement') }}{% endif %}
+
+ {%- endif %}
+ {%- endfor %}
{%- endif %}
{%- endfor %}
-{%- endfor %}
-Когда отвечаешь, обращайся к собеседнику по имени Дэйв.
-"""
+{%- endfor %}"""
ID_GIGACHAT = "gigachat"
ID_YANDEX_GPT = "yandexgpt"
@@ -69,14 +81,14 @@
DEFAULT_MODELS_YANDEX_GPT = ["", "YandexGPT", "YandexGPT Lite", "Summary"]
MODELS_OPENAI = [
"",
+ "gpt-4.1",
+ "gpt-4.1-mini",
+ "gpt-4.1-nano",
"gpt-4o",
"gpt-4o-mini",
- "gpt-4-turbo",
- "gpt-4",
- "gpt-3.5-turbo",
- "o1",
- "o1-mini",
+ "o3",
"o3-mini",
+ "o4-mini",
]
ENGINE_MODELS = {
UNIQUE_ID_GIGACHAT: MODELS_GIGACHAT,
@@ -85,9 +97,12 @@
}
DEFAULT_MODEL = {
ID_GIGACHAT: None,
- ID_OPENAI: "gpt-4o-mini",
+ ID_OPENAI: "gpt-4.1-mini",
ID_YANDEX_GPT: None,
}
+CONF_LLM_HASS_API = "llm_hass_api"
CONF_API_KEY = "api_key"
CONF_FOLDER_ID = "folder_id"
+
+MAX_TOOL_ITERATIONS = 10
diff --git a/custom_components/smartchain/conversation.py b/custom_components/smartchain/conversation.py
new file mode 100644
index 0000000..c234fcd
--- /dev/null
+++ b/custom_components/smartchain/conversation.py
@@ -0,0 +1,239 @@
+"""Conversation entity for SmartChain integration."""
+
+import json
+import logging
+from collections.abc import AsyncIterable
+from typing import Any, Literal
+
+import voluptuous_openapi
+from home_assistant_intents import get_languages
+from homeassistant.components import conversation
+from homeassistant.components.conversation import (
+ ChatLog,
+ ConversationEntity,
+ ConversationInput,
+ ConversationResult,
+)
+from homeassistant.components.conversation.chat_log import (
+ AssistantContent,
+ SystemContent,
+ ToolResultContent,
+ UserContent,
+)
+from homeassistant.config_entries import ConfigEntry
+from homeassistant.helpers import intent, llm, template
+from homeassistant.helpers.entity_platform import AddEntitiesCallback
+from langchain_core.messages import (
+ AIMessage,
+ BaseMessage,
+ HumanMessage,
+ SystemMessage,
+ ToolMessage,
+)
+
+from .const import (
+ CONF_CHAT_HISTORY,
+ CONF_LLM_HASS_API,
+ CONF_PROCESS_BUILTIN_SENTENCES,
+ CONF_PROMPT,
+ DEFAULT_CHAT_HISTORY,
+ DEFAULT_DEVICES_PROMPT,
+ DEFAULT_PROCESS_BUILTIN_SENTENCES,
+ DEFAULT_PROMPT,
+ DOMAIN,
+ MAX_TOOL_ITERATIONS,
+)
+
+LOGGER = logging.getLogger(__name__)
+
+
+async def async_setup_entry(
+ hass,
+ config_entry: ConfigEntry,
+ async_add_entities: AddEntitiesCallback,
+) -> None:
+ """Set up conversation entity."""
+ async_add_entities([SmartChainConversationEntity(config_entry)])
+
+
+def _ha_tool_to_dict(tool: llm.Tool) -> dict[str, Any]:
+ """Convert HA llm.Tool to dict for LangChain bind_tools."""
+ parameters = voluptuous_openapi.convert(tool.parameters)
+ return {
+ "name": tool.name,
+ "description": tool.description or "",
+ "parameters": parameters,
+ }
+
+
+class SmartChainConversationEntity(ConversationEntity):
+ """SmartChain conversation entity using ConversationEntity API."""
+
+ _attr_has_entity_name = True
+ _attr_name = None
+ _attr_supports_streaming = True
+
+ def __init__(self, entry: ConfigEntry) -> None:
+ """Initialize the entity."""
+ self.entry = entry
+ self._attr_unique_id = entry.entry_id
+
+ @property
+ def supported_languages(self) -> list[str] | Literal["*"]:
+ """Return a list of supported languages."""
+ return get_languages()
+
+ async def _async_handle_message(
+ self,
+ user_input: ConversationInput,
+ chat_log: ChatLog,
+ ) -> ConversationResult:
+ """Handle a conversation message via ChatLog API."""
+ options = self.entry.options
+ llm_hass_api = options.get(CONF_LLM_HASS_API)
+ user_prompt = options.get(CONF_PROMPT, DEFAULT_PROMPT)
+
+ if llm_hass_api:
+ try:
+ await chat_log.async_provide_llm_data(
+ user_input.as_llm_context(DOMAIN),
+ llm_hass_api,
+ user_prompt,
+ user_input.extra_system_prompt,
+ )
+ except conversation.ConverseError as err:
+ return err.as_conversation_result()
+ else:
+ raw_prompt = user_prompt + DEFAULT_DEVICES_PROMPT
+ prompt = template.Template(raw_prompt, self.hass).async_render(
+ {"ha_name": self.hass.config.location_name},
+ parse_result=False,
+ )
+ chat_log.content[0] = SystemContent(content=prompt)
+
+ use_builtin = options.get(
+ CONF_PROCESS_BUILTIN_SENTENCES, DEFAULT_PROCESS_BUILTIN_SENTENCES
+ )
+ if use_builtin and not llm_hass_api:
+ from homeassistant.components.conversation import agent_manager
+
+ default_agent = agent_manager.async_get_agent(self.hass, None)
+ default_response = await default_agent.async_process(user_input)
+
+ if default_response.response.intent:
+ speech = (
+ default_response.response.speech.get("plain", {}).get("speech", "")
+ )
+ chat_log.async_add_assistant_content_without_tools(
+ AssistantContent(
+ agent_id=user_input.agent_id,
+ content=speech,
+ )
+ )
+ return default_response
+
+ client = self.entry.runtime_data
+ tools = (
+ [_ha_tool_to_dict(tool) for tool in chat_log.llm_api.tools]
+ if chat_log.llm_api
+ else []
+ )
+ bound_client = client.bind_tools(tools) if tools else client
+
+ for _iteration in range(MAX_TOOL_ITERATIONS):
+ chat_history_enabled = options.get(
+ CONF_CHAT_HISTORY, DEFAULT_CHAT_HISTORY
+ )
+ if chat_history_enabled:
+ messages = _chatlog_to_langchain(chat_log)
+ else:
+ messages = [
+ SystemMessage(content=chat_log.content[0].content),
+ HumanMessage(content=user_input.text),
+ ]
+
+ try:
+ async for _content in chat_log.async_add_delta_content_stream(
+ user_input.agent_id,
+ _async_langchain_stream(bound_client, messages),
+ ):
+ pass
+ except Exception as err:
+ LOGGER.exception("Unexpected exception %s", type(err))
+ response = intent.IntentResponse(language=user_input.language)
+ response.async_set_error(
+ intent.IntentResponseErrorCode.UNKNOWN,
+ f"Houston we have a problem: {err}",
+ )
+ return ConversationResult(
+ conversation_id=chat_log.conversation_id, response=response
+ )
+
+ if not chat_log.unresponded_tool_results:
+ break
+
+ return conversation.async_get_result_from_chat_log(user_input, chat_log)
+
+
+def _chatlog_to_langchain(chat_log: ChatLog) -> list[BaseMessage]:
+ """Convert ChatLog content to LangChain message list."""
+ messages: list[BaseMessage] = []
+ for content in chat_log.content:
+ if isinstance(content, SystemContent):
+ messages.append(SystemMessage(content=content.content))
+ elif isinstance(content, UserContent):
+ messages.append(HumanMessage(content=content.content))
+ elif isinstance(content, AssistantContent):
+ if content.tool_calls:
+ tool_calls = [
+ {
+ "id": tc.id,
+ "name": tc.tool_name,
+ "args": tc.tool_args,
+ }
+ for tc in content.tool_calls
+ ]
+ messages.append(
+ AIMessage(
+ content=content.content or "",
+ tool_calls=tool_calls,
+ )
+ )
+ elif content.content:
+ messages.append(AIMessage(content=content.content))
+ elif isinstance(content, ToolResultContent):
+ messages.append(
+ ToolMessage(
+ content=json.dumps(content.tool_result),
+ tool_call_id=content.tool_call_id,
+ name=content.tool_name,
+ )
+ )
+ return messages
+
+
+async def _async_langchain_stream(
+ client: Any, messages: list[BaseMessage]
+) -> AsyncIterable[dict[str, Any]]:
+ """Convert LangChain astream chunks to HA delta dicts."""
+ first = True
+ async for chunk in client.astream(messages):
+ delta: dict[str, Any] = {}
+ if first:
+ delta["role"] = "assistant"
+ first = False
+ if chunk.content:
+ delta["content"] = chunk.content
+
+ if chunk.tool_calls:
+ delta["tool_calls"] = [
+ llm.ToolInput(
+ tool_name=tc["name"],
+ tool_args=tc["args"],
+ id=tc["id"],
+ )
+ for tc in chunk.tool_calls
+ ]
+
+ if delta:
+ yield delta
diff --git a/custom_components/gigachain/manifest.json b/custom_components/smartchain/manifest.json
similarity index 63%
rename from custom_components/gigachain/manifest.json
rename to custom_components/smartchain/manifest.json
index 540523d..e56c4da 100644
--- a/custom_components/gigachain/manifest.json
+++ b/custom_components/smartchain/manifest.json
@@ -1,14 +1,14 @@
{
- "domain": "gigachain",
- "name": "GigaChain",
+ "domain": "smartchain",
+ "name": "SmartChain",
"codeowners": ["@gritaro"],
"config_flow": true,
"dependencies": ["conversation"],
- "documentation": "https://github.com/gritaro/gigachain",
+ "documentation": "https://github.com/gritaro/ha-smartchain",
"homekit": {},
"integration_type": "service",
"iot_class": "cloud_polling",
- "issue_tracker": "https://github.com/gritaro/gigachain/issues",
+ "issue_tracker": "https://github.com/gritaro/ha-smartchain/issues",
"requirements": [
"home-assistant-intents",
"langchain-gigachat>=0.3.0",
@@ -16,5 +16,5 @@
"langchain-community>=0.4.0",
"yandexcloud==0.295.0"
],
- "version": "0.5.0"
+ "version": "0.7.0"
}
diff --git a/custom_components/gigachain/strings.json b/custom_components/smartchain/strings.json
similarity index 92%
rename from custom_components/gigachain/strings.json
rename to custom_components/smartchain/strings.json
index e6d3296..1fe8687 100644
--- a/custom_components/gigachain/strings.json
+++ b/custom_components/smartchain/strings.json
@@ -2,7 +2,7 @@
"config": {
"step": {
"user": {
- "title": "GigaChain configuration - select engine",
+ "title": "SmartChain configuration - select engine",
"data": {
"engine": "LLM Engine"
}
@@ -47,6 +47,7 @@
"init": {
"title": "Model configuration",
"data": {
+ "llm_hass_api": "Assist API (Control HA devices)",
"prompt": "Prompt Template",
"model": "Completion Model",
"model_user": "Custom Model Name (leave empty to use from list above)",
diff --git a/custom_components/gigachain/translations/en.json b/custom_components/smartchain/translations/en.json
similarity index 92%
rename from custom_components/gigachain/translations/en.json
rename to custom_components/smartchain/translations/en.json
index e6d3296..1fe8687 100644
--- a/custom_components/gigachain/translations/en.json
+++ b/custom_components/smartchain/translations/en.json
@@ -2,7 +2,7 @@
"config": {
"step": {
"user": {
- "title": "GigaChain configuration - select engine",
+ "title": "SmartChain configuration - select engine",
"data": {
"engine": "LLM Engine"
}
@@ -47,6 +47,7 @@
"init": {
"title": "Model configuration",
"data": {
+ "llm_hass_api": "Assist API (Control HA devices)",
"prompt": "Prompt Template",
"model": "Completion Model",
"model_user": "Custom Model Name (leave empty to use from list above)",
diff --git a/custom_components/gigachain/translations/ru.json b/custom_components/smartchain/translations/ru.json
similarity index 71%
rename from custom_components/gigachain/translations/ru.json
rename to custom_components/smartchain/translations/ru.json
index 68f3113..5ceae8d 100644
--- a/custom_components/gigachain/translations/ru.json
+++ b/custom_components/smartchain/translations/ru.json
@@ -2,20 +2,20 @@
"config": {
"step": {
"user": {
- "title": "GigaChain конфигурация - выбор LLM",
+ "title": "SmartChain - выбор LLM провайдера",
"data": {
- "engine": "Большая языковая модель"
+ "engine": "LLM провайдер"
}
},
"gigachat": {
- "title": "Конфигурация GigaChat",
+ "title": "GigaChat",
"data": {
"api_key": "Авторизационные данные",
"skip_validation": "Пропустить проверку"
}
},
"yandexgpt": {
- "title": "Конфигурация YandexGPT",
+ "title": "YandexGPT",
"data": {
"api_key": "API ключ",
"folder_id": "Идентификатор каталога (Folder ID)",
@@ -23,7 +23,7 @@
}
},
"openai": {
- "title": "Конфигурация OpenAI",
+ "title": "OpenAI",
"data": {
"api_key": "API ключ",
"skip_validation": "Пропустить проверку"
@@ -31,7 +31,7 @@
}
},
"abort": {
- "already_configured": "Эта модель уже настроена"
+ "already_configured": "Этот провайдер уже настроен"
},
"error": {
"cannot_connect": "Не удаётся подключиться",
@@ -45,16 +45,17 @@
},
"step": {
"init": {
- "title": "Конфигурация модели",
+ "title": "Настройки модели",
"data": {
+ "llm_hass_api": "Assist API (управление устройствами HA)",
"prompt": "Системный промпт",
"model": "Модель",
- "model_user": "Своё имя модели (оставьте пустым для использования имени из списка)",
+ "model_user": "Своё имя модели (оставьте пустым для использования из списка)",
"temperature": "Температура",
"max_tokens": "Максимум токенов",
"profanity": "Цензура",
"verify_ssl": "Проверка SSL сертификатов",
- "process_builtin_sentences": "Использовать встроенный HA командный процессор",
+ "process_builtin_sentences": "Встроенный командный процессор HA",
"chat_history": "История сообщений"
}
}
diff --git a/docs/COMPETITIVE_ANALYSIS.md b/docs/COMPETITIVE_ANALYSIS.md
new file mode 100644
index 0000000..5226c60
--- /dev/null
+++ b/docs/COMPETITIVE_ANALYSIS.md
@@ -0,0 +1,382 @@
+# GigaChain — Конкурентный анализ и точки роста
+
+Дата: 2026-03-10 | Версия: 0.5.0
+
+## Оглавление
+
+1. [Конкуренты — интеграции HA для LLM](#1-конкуренты--интеграции-ha-для-llm)
+2. [Что есть у конкурентов, чего нет у нас](#2-что-есть-у-конкурентов-чего-нет-у-нас)
+3. [Российские и китайские модели](#3-российские-и-китайские-модели--кого-можно-подключить)
+4. [Легковесные локальные модели](#4-легковесные-локальные-модели)
+5. [Точки роста и пути развития](#5-точки-роста-и-пути-развития)
+6. [Стратегическое позиционирование](#6-стратегическое-позиционирование)
+7. [Источники](#7-источники)
+
+---
+
+## 1. Конкуренты — интеграции HA для LLM
+
+### Официальные интеграции (встроены в HA core)
+
+| Интеграция | Провайдер | Device Control | AI Task | Streaming | Vision | MCP |
+|---|---|---|---|---|---|---|
+| OpenAI Conversation | OpenAI | Assist API | да | да | да | да |
+| Anthropic | Claude | Assist API | да | да | нет | да |
+| Google Gemini | Gemini | Assist API | да | да | да | да |
+| Ollama | Локальные | Assist API | да | да | нет | да |
+| OpenRouter | 400+ моделей | Assist API | да | да | нет | да |
+
+Все официальные интеграции поддерживают:
+- Assist API для управления устройствами
+- AI Task entity для генерации данных в автоматизациях
+- Sub-entries (несколько агентов с разными моделями через одну интеграцию)
+- MCP (Model Context Protocol) для расширения возможностей внешними инструментами
+- Streaming ответов
+- Conversational follow-ups (LLM может задавать уточняющие вопросы)
+- Per-device LLM assignment (разный LLM для разных устройств)
+
+### Custom-интеграции (HACS)
+
+#### Extended OpenAI Conversation (~1.5k stars)
+- GitHub: https://github.com/jekalmin/extended_openai_conversation
+- **Function calling** — вызов сервисов HA через OpenAI API
+- **Создание автоматизаций** через естественный язык
+- **Чтение истории состояний** — LLM знает, что было раньше
+- **REST API** — запросы к внешним API
+- **Веб-скрейпинг** — получение данных с веб-страниц
+- **Skill-система** — загружаемые навыки из директории
+- **Multi-agent** — Dispatcher Agent маршрутизирует запросы между специализированными агентами
+- **Attach Username** — персонализация по имени пользователя
+- Поддержка native functions: `execute_service`, `add_automation`, `get_history`
+
+#### YandexGPT (black-roland, 38 stars)
+- GitHub: https://github.com/black-roland/homeassistant-yandexgpt
+- **Управление устройствами** — включение/выключение света, регулировка температуры, запуск скриптов
+- **YandexART** — генерация изображений
+- **Telegram-бот** — использование как backend для Telegram
+- **Yandex SpeechKit** — companion-интеграция для STT/TTS
+- Последний релиз: v1.5.5 (декабрь 2025)
+- Лицензия: MPL-2.0
+
+#### Cloud.ru Foundation Models (black-roland, новый)
+- GitHub: https://github.com/black-roland/homeassistant-cloud-ru-ai
+- **Открытые модели**: GPT-OSS-120b, Qwen3, Llama, DeepSeek R1 Distill, GLM-4.5, T-Pro
+- **Управление устройствами** — полный контроль через чат
+- Основан на официальной интеграции OpenAI HA
+- Лицензия: Apache 2.0
+
+#### Home-LLM (acon96, ~3k stars)
+- GitHub: https://github.com/acon96/home-llm
+- **Полностью локальный** — никаких облачных сервисов
+- **Fine-tuned модели** — Home-3B-v3 (97% точность function calling), Home-1B-v3
+- **Tool calling** — переписан для поддержки agentic tool use loop
+- **AI Task entity** — генерация данных для автоматизаций
+- **Multi-language** — EN, DE, FR, ES, PL
+- **CPU-friendly** — работает на Raspberry Pi
+- Backends: Ollama, llama.cpp, OpenAI-compatible API
+
+#### LLM Vision (~1.5k stars)
+- GitHub: https://github.com/valentinfrlch/ha-llmvision
+- **Мультимодальный** — анализ изображений, видео, live камер, Frigate events
+- **Timeline** — хранит историю событий камер
+- **Распознавание** — люди, номерные знаки, объекты
+- **Голосовые запросы** — "Была ли активность во дворе вчера?"
+- Провайдеры: OpenAI, Anthropic, Gemini, Ollama, OpenRouter, и др.
+
+#### GigaChain (наш, 15 stars)
+- GigaChat + YandexGPT + OpenAI через LangChain
+- Streaming ответов
+- ChatLog для истории
+- Builtin sentence processor
+- Системный промпт с Jinja2
+
+---
+
+## 2. Что есть у конкурентов, чего нет у нас
+
+### Критические отставания
+
+| Фича | У кого есть | Описание |
+|---|---|---|
+| Управление устройствами (Assist API) | Все official, Extended OpenAI, YandexGPT, Cloud.ru | LLM может включать свет, менять температуру, запускать сценарии |
+| AI Task entity | Все official, Home-LLM | Генерация данных для автоматизаций через `ai_task.generate_data` |
+| MCP (Model Context Protocol) | Все official | Расширение возможностей агента внешними инструментами |
+| Function calling / вызов сервисов | Extended OpenAI, все official | LLM вызывает произвольные сервисы HA |
+| Vision / мультимодальность | OpenAI, Gemini, LLM Vision | Анализ камер и изображений |
+| Генерация изображений | YandexGPT (YandexART) | Создание изображений по описанию |
+| Создание автоматизаций через AI | Extended OpenAI | Генерация автоматизаций HA из естественного языка |
+| Доступ к истории состояний | Extended OpenAI | LLM анализирует тренды и прошлые события |
+
+### Менее критичные
+
+| Фича | У кого есть |
+|---|---|
+| Multi-agent (Dispatcher + специализированные) | Extended OpenAI |
+| Skill-система (загружаемые навыки) | Extended OpenAI |
+| Telegram-бот | YandexGPT |
+| STT/TTS от того же провайдера | YandexGPT + SpeechKit |
+| Prompt caching | llama.cpp custom-conversation |
+| Sub-entries (несколько агентов) | Все official (HA 2025.8+) |
+| Conversational follow-ups | Все official |
+| Per-device LLM assignment | Все official |
+
+---
+
+## 3. Российские и китайские модели — кого можно подключить
+
+### Российские модели с API
+
+#### GigaChat 2.0 (Сбер) — уже подключён
+- Линейка: Lite / Pro / MAX
+- Контекст: до 128K токенов
+- Мультимодальность: да (GigaChat 2.0)
+- Генерация изображений: да (Kandinsky)
+- Цена: ~650 руб/1M токенов (MAX), 1M бесплатных токенов/месяц для разработчиков
+- LangChain: `langchain-gigachat` (подключён)
+- Function calling: поддерживается
+
+#### YandexGPT 4 / Alice AI LLM (Яндекс) — уже подключён
+- Линейка: Lite / Pro
+- Контекст: до 32K токенов (до 60 страниц)
+- Цена: ~1220 руб/1M токенов (Pro)
+- LangChain: `langchain_community.chat_models.ChatYandexGPT` (подключён)
+- Доп. сервисы: YandexART (генерация изображений), SpeechKit (STT/TTS)
+- Примечание: в октябре 2025 переименован в Alice AI LLM
+
+#### T-Pro 2.0 (Т-Банк / Т-Технологии) — НЕ подключён
+- Параметры: 32B
+- Лицензия: Apache 2.0 (полностью открытая)
+- Гибридный reasoning (быстрые ответы + многошаговое рассуждение)
+- На 30% экономичнее Qwen3 и DeepSeek R1-Distil на русском
+- Лидер бенчмарков MERA, ruMMLU, ruArena Hard для русского
+- Основана на Qwen3 32B с улучшенным кириллическим токенизатором
+- Доступ: HuggingFace, self-hosted через Ollama/vLLM
+- **Рекомендация: подключить через Ollama backend**
+
+#### T-Lite (Т-Банк) — НЕ подключён
+- Параметры: 7B
+- Лицензия: Apache 2.0
+- Компактная модель для устройств со средней производительностью
+- Доступ: HuggingFace, Ollama
+- **Рекомендация: подключить через Ollama как легковесную опцию**
+
+#### Cotype Pro 2.5 (MTS AI / MWS AI) — НЕ подключён
+- Лидер среди российских LLM в бенчмарке MERA
+- Агентные навыки: в 10 раз эффективнее Cotype Pro 2
+- Превосходит Qwen3-32B на 22% по точности на русском
+- Доступ: enterprise API (MWS Cloud)
+- **Рекомендация: рассмотреть при наличии API**
+
+#### Cotype Nano (MTS AI) — НЕ подключён
+- Открытая модель, работает на мобильных устройствах и ноутбуках
+- Лучшие результаты в своём классе на Ru Arena Hard
+- **Рекомендация: подключить через Ollama**
+
+### Китайские модели (доступны из России)
+
+#### DeepSeek V3 / R1 — НЕ подключён
+- V3: general-purpose, tool calling, structured output
+- R1: reasoning, chain-of-thought
+- LangChain: `langchain-deepseek` (`ChatDeepSeek`)
+- Цена: самая низкая на рынке (~$0.14/1M input tokens)
+- Доступ из РФ: API (возможны проблемы с блокировкой IP Роскомнадзором), self-hosted через Ollama
+- **Рекомендация: подключить как самый дешёвый cloud-провайдер**
+
+#### Qwen 3 (Alibaba) — НЕ подключён
+- Модели от 0.6B до 235B параметров
+- Самая скачиваемая серия моделей на HuggingFace (2025-2026)
+- Reasoning mode, tool calling
+- LangChain: `ChatOllama` или Cloud.ru
+- **Рекомендация: подключить через Ollama backend**
+
+#### GLM-4.5 (Zhipu AI) — НЕ подключён
+- Доступ: Cloud.ru Foundation Models
+- **Рекомендация: подключить через Cloud.ru или Ollama**
+
+#### Baichuan, Yi, MiniCPM — НЕ подключены
+- Open-source, self-hosted через Ollama
+- **Рекомендация: автоматически доступны при поддержке Ollama**
+
+---
+
+## 4. Легковесные локальные модели
+
+Для пользователей без мощного GPU или с Raspberry Pi:
+
+| Модель | Параметры | RAM | Язык | Особенности |
+|---|---|---|---|---|
+| Home-3B-v3 | 3B | ~2GB | EN/DE/FR/ES | 97% точность function calling HA |
+| Home-1B-v3 | 1B | ~1GB | EN | Raspberry Pi compatible |
+| T-Lite | 7B | ~4GB | RU | лучшая для русского в классе 7B |
+| T-Pro 2.0 | 32B | ~18GB | RU | лидер русскоязычных бенчмарков |
+| Qwen3 | 0.6B-4B | 0.5-3GB | RU/EN/ZH | reasoning, tool calling |
+| Phi-4-mini | 3.8B | ~2GB | EN | Microsoft, компактная |
+| Gemma 3 | 1B-4B | 1-3GB | EN | Google, vision support |
+| DeepSeek R1 Distill | 1.5B-14B | 1-8GB | EN/ZH | reasoning |
+| Cotype Nano | small | ~2GB | RU | MTS AI, открытая |
+| MiniCPM | 1.2B-8B | 1-4GB | ZH/EN | OpenBMB, компактная |
+
+Все локальные модели доступны через **Ollama** — единый backend для self-hosted LLM.
+
+---
+
+## 5. Точки роста и пути развития
+
+### Приоритет: Высокий (конкурентный паритет)
+
+#### 5.1 Управление устройствами через Assist API
+- **Что:** Использовать `chat_log.async_provide_llm_data()` для доступа к HA tools
+- **Зачем:** Главная фича, которую имеют ВСЕ конкуренты. Без неё GigaChain — только чат-бот, не smart home agent
+- **Как:** HA LLM API предоставляет intents для управления exposed entities. Нужно передать tools в LLM и обработать tool calls
+- **Сложность:** Средняя. GigaChat и DeepSeek поддерживают function calling. Паттерн задокументирован в HA developer docs
+
+#### 5.2 AI Task entity
+- **Что:** Добавить `AITaskEntity` с методом `_async_generate_data()`
+- **Зачем:** Позволит использовать GigaChain в автоматизациях, скриптах, шаблонах через `ai_task.generate_data`
+- **Как:** Новый entity наряду с ConversationEntity, может разделять общую логику обработки chat_log
+- **Сложность:** Низкая-средняя
+
+#### 5.3 Новые провайдеры LLM
+- **DeepSeek** (`pip install langchain-deepseek`) — `ChatDeepSeek`, самый дешёвый, tool calling
+- **Ollama** (`pip install langchain-ollama`) — `ChatOllama`, все локальные модели (T-Pro, Qwen, Llama, DeepSeek)
+- **Anthropic** (`pip install langchain-anthropic`) — `ChatAnthropic`, extended thinking
+- **Зачем:** Расширение аудитории, поддержка локальных моделей, снижение стоимости
+- **Сложность:** Низкая — архитектура через LangChain уже позволяет добавлять провайдеров в `client_util.py`
+
+### Приоритет: Средний (дифференциация)
+
+#### 5.4 Function calling / вызов сервисов HA
+- **Что:** LLM вызывает произвольные сервисы HA (свет, климат, сценарии)
+- **Зачем:** Extended OpenAI Conversation — самая популярная custom-интеграция именно из-за этой фичи
+- **Как:** Определить tool specs для `execute_service`, `get_history`, передавать в LLM, обрабатывать tool calls в цикле
+- **Сложность:** Средняя-высокая
+
+#### 5.5 Vision / мультимодальность
+- **Что:** Анализ изображений с камер через LLM
+- **Зачем:** GigaChat 2.0 поддерживает мультимодальность. Можно анализировать камеры без LLM Vision
+- **Как:** Передавать изображения как attachments в LLM запрос
+- **Сложность:** Средняя
+
+#### 5.6 Генерация изображений
+- **Что:** GigaChat (Kandinsky) и YandexART для создания изображений
+- **Зачем:** Уникальная фича для российского рынка. У конкурента YandexGPT уже есть
+- **Как:** Отдельный сервис или entity для генерации
+- **Сложность:** Средняя
+
+#### 5.7 Sub-entries (несколько агентов)
+- **Что:** Позволить создавать несколько conversation agents с разными моделями/промптами через одну интеграцию
+- **Зачем:** Паттерн из HA 2025.8+. Один агент для чата, другой для device control, третий для генерации
+- **Сложность:** Средняя
+
+#### 5.8 MCP (Model Context Protocol)
+- **Что:** Интеграция с MCP серверами для расширения возможностей агента
+- **Зачем:** Все official-интеграции поддерживают. Даёт доступ к новостям, todo-спискам, внешним данным
+- **Сложность:** Средняя-высокая
+
+### Приоритет: Низкий (nice to have)
+
+#### 5.9 Доступ к истории состояний
+- LLM анализирует тренды и прошлые события ("Какая была температура вчера?")
+
+#### 5.10 Telegram-бот
+- Использовать GigaChain как backend для Telegram (как у YandexGPT)
+
+#### 5.11 STT/TTS интеграция
+- Связка с Yandex SpeechKit или GigaChat TTS для полного voice pipeline на русском
+
+#### 5.12 Prompt caching
+- Кэширование промптов для ускорения повторных запросов (как в llama.cpp)
+
+#### 5.13 Multi-agent
+- Dispatcher agent маршрутизирует запросы между специализированными агентами
+
+#### 5.14 Skill-система
+- Загружаемые "навыки" для разных доменов (погода, расписание, рецепты)
+
+#### 5.15 Conversational follow-ups
+- LLM задаёт уточняющие вопросы, HA слушает ответ
+
+---
+
+## 6. Стратегическое позиционирование
+
+### Текущее УТП (Unique Selling Proposition)
+
+GigaChain — **единственная** HA интеграция, объединяющая GigaChat + YandexGPT + OpenAI в одном компоненте через LangChain. Это позволяет:
+- Переключаться между провайдерами без переустановки
+- Использовать единый интерфейс для разных LLM
+- Легко добавлять новые модели через LangChain экосистему
+
+### Слабые стороны
+
+- Нет управления устройствами — главный разрыв с конкурентами
+- Нет AI Task — не может использоваться в автоматизациях
+- Нет локальных моделей (Ollama) — зависимость от cloud API
+- Небольшое сообщество (15 stars vs 3k у Home-LLM)
+
+### Рекомендуемая дорожная карта
+
+```mermaid
+gantt
+ title GigaChain Roadmap
+ dateFormat YYYY-MM
+ section Высокий приоритет
+ Assist API + Device Control :2026-03, 2026-04
+ AI Task entity :2026-04, 2026-05
+ DeepSeek + Ollama провайдеры :2026-04, 2026-05
+ section Средний приоритет
+ Function calling :2026-05, 2026-06
+ Vision / мультимодальность :2026-06, 2026-07
+ Sub-entries :2026-06, 2026-07
+ Генерация изображений :2026-07, 2026-08
+ section Низкий приоритет
+ Multi-agent :2026-08, 2026-09
+ Telegram-бот :2026-09, 2026-10
+```
+
+### Целевая аудитория
+
+1. **Российские пользователи HA** — GigaChat + YandexGPT без VPN
+2. **Privacy-conscious** — Ollama + T-Pro/Qwen для полностью локального решения
+3. **Мультипровайдерные** — один компонент вместо нескольких интеграций
+4. **Разработчики** — LangChain экосистема для кастомизации
+
+---
+
+## 7. Источники
+
+### Официальная документация HA
+- https://www.home-assistant.io/blog/2025/09/11/ai-in-home-assistant/
+- https://developers.home-assistant.io/docs/core/llm/
+- https://www.home-assistant.io/integrations/openai_conversation/
+- https://www.home-assistant.io/integrations/anthropic/
+- https://www.home-assistant.io/integrations/google_generative_ai_conversation/
+- https://www.home-assistant.io/integrations/ollama/
+- https://www.home-assistant.io/integrations/open_router/
+- https://www.home-assistant.io/integrations/ai_task/
+- https://www.home-assistant.io/blog/2025/08/06/release-20258/
+- https://developers.home-assistant.io/docs/core/entity/ai-task/
+- https://developers.home-assistant.io/docs/core/entity/conversation
+
+### Custom-интеграции
+- https://github.com/jekalmin/extended_openai_conversation
+- https://github.com/black-roland/homeassistant-yandexgpt
+- https://github.com/black-roland/homeassistant-cloud-ru-ai
+- https://github.com/acon96/home-llm
+- https://github.com/valentinfrlch/ha-llmvision
+
+### Российские LLM
+- https://vc.ru/ai/2733649-rossiyskie-neuroseti-2026-modeli-i-servisy-dlya-biznesa
+- https://habr.com/ru/companies/tbank/articles/928956/
+- https://mts.ai/tech/mts-ai-releases-cotype-pro-2-second-generation-business-focused-llm/
+- https://www.tbank.ru/about/news/11122024-the-t-technologies-group-has-introduced-the-worlds-most-efficient-open-large-language-models-in-russian/
+
+### Китайские LLM
+- https://intuitionlabs.ai/articles/chinese-open-source-llms-2025
+- https://changelog.langchain.com/announcements/deepseek-integration-in-langchain
+- https://www.index.dev/blog/chinese-ai-models-deepseek
+
+### LangChain интеграции
+- https://docs.langchain.com/oss/python/integrations/providers/yandex
+- https://docs.langchain.com/oss/python/integrations/chat/deepseek
+- https://ollama.com/fixt/home-3b-v3
diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md
new file mode 100644
index 0000000..d47e5a4
--- /dev/null
+++ b/docs/ROADMAP.md
@@ -0,0 +1,371 @@
+# GigaChain — Дорожная карта развития
+
+Дата: 2026-03-10 | Текущая версия: 0.6.0
+
+## Оглавление
+
+1. [Текущее состояние](#1-текущее-состояние)
+2. [Фаза 1 — Конкурентный паритет](#2-фаза-1--конкурентный-паритет-v07--v09)
+3. [Фаза 2 — Дифференциация](#3-фаза-2--дифференциация-v10--v13)
+4. [Фаза 3 — Лидерство](#4-фаза-3--лидерство-v14)
+5. [Технические детали по задачам](#5-технические-детали-по-задачам)
+
+---
+
+## 1. Текущее состояние
+
+### Реализовано (v0.1–v0.6)
+
+| Версия | Что сделано |
+|--------|-------------|
+| 0.1.x | Базовая интеграция: GigaChat + YandexGPT + OpenAI, Config/Options Flow, история диалогов, Jinja2 промпт |
+| 0.2.0 | Исправление блокировки event loop, deprecated API, утечки памяти, удаление Anyscale |
+| 0.2.1 | verify_ssl для GigaChat, обновление CI (Python 3.12, ruff) |
+| 0.3.0 | Миграция на `ConversationEntity` API, `conversation.py`, pytest (20 тестов) |
+| 0.4.0 | Миграция на ChatLog, langchain-gigachat/langchain-openai, CI pytest (26 тестов) |
+| 0.5.0 | Streaming ответов через `astream()` + `async_add_delta_content_stream()` (29 тестов) |
+| 0.6.0 | **Assist API** — управление устройствами через tool calling, LLM API selector, обновление промпта и моделей (34 теста) |
+
+### Текущая архитектура
+
+```mermaid
+graph TB
+ subgraph "GigaChain v0.6.0"
+ CF[Config Flow] --> CU[client_util.py]
+ CU --> GC[GigaChat]
+ CU --> YGP[YandexGPT]
+ CU --> OAI[OpenAI]
+
+ CE[ConversationEntity] --> CL[ChatLog]
+ CE --> ST[Streaming]
+ CE --> AA[Assist API]
+ AA --> TC[Tool Calling Loop]
+ TC --> BT[bind_tools]
+ end
+
+ subgraph "Home Assistant"
+ HA_LLM[HA LLM API] --> AA
+ HA_TOOLS[Intents & Services] --> HA_LLM
+ end
+```
+
+### Разрыв с конкурентами
+
+| Фича | Official HA | Extended OpenAI | YandexGPT | Home-LLM | GigaChain |
+|-------|:-----------:|:---------------:|:---------:|:--------:|:---------:|
+| Assist API / Device Control | + | + | + | + | **+ (v0.6)** |
+| AI Task entity | + | - | - | + | - |
+| Streaming | + | + | - | + | **+ (v0.5)** |
+| MCP | + | - | - | - | - |
+| Vision | + (OpenAI, Gemini) | - | - | - | - |
+| Генерация изображений | - | - | + | - | - |
+| Function calling (custom) | - | + | + | + | - |
+| Sub-entries | + | - | - | - | - |
+| Ollama / локальные модели | + | - | - | + | - |
+| Multi-agent | - | + | - | - | - |
+| Telegram-бот | - | - | + | - | - |
+| История состояний | - | + | - | - | - |
+
+---
+
+## 2. Фаза 1 — Конкурентный паритет (v0.7 – v0.9)
+
+Цель: закрыть критические разрывы с конкурентами, стать полноценным smart home agent.
+
+### v0.7 — AI Task entity
+
+**Приоритет:** Высокий
+**Сложность:** Низкая-средняя
+**Зависимости:** нет
+
+**Что:**
+- Добавить `AITaskEntity` с методом `_async_generate_data(task, chat_log)`
+- Позволяет использовать GigaChain в автоматизациях HA через `ai_task.generate_data`
+- Примеры: "Составь план уборки на основе загрязнённости комнат", "Проанализируй расход электричества за неделю"
+
+**Файлы:**
+- `custom_components/gigachain/ai_task.py` — новый файл с `GigaChainAITaskEntity`
+- `custom_components/gigachain/__init__.py` — добавить `Platform.AI_TASK`
+- `custom_components/gigachain/manifest.json` — добавить `"ai_task"` в dependencies
+- `tests/test_ai_task.py` — тесты
+
+**Реализация:**
+```python
+class GigaChainAITaskEntity(AITaskEntity):
+ async def _async_generate_data(
+ self, task: ai_task.GenData, chat_log: ChatLog
+ ) -> None:
+ # Предоставить LLM данные (tools, prompt)
+ await chat_log.async_provide_llm_data(...)
+ # Вызвать LLM через общую логику streaming + tool calling
+ # Результат записывается в chat_log автоматически
+```
+
+**Референсы:**
+- https://developers.home-assistant.io/docs/core/entity/ai-task/
+- `homeassistant.components.openai_conversation.ai_task`
+
+---
+
+### v0.8 — Новые провайдеры LLM (Ollama, DeepSeek, Anthropic)
+
+**Приоритет:** Высокий
+**Сложность:** Низкая
+**Зависимости:** нет
+
+**Что:**
+Добавить 3 новых провайдера через LangChain. Архитектура уже позволяет — нужно расширить `client_util.py` и Config Flow.
+
+#### 0.8.1 — Ollama (локальные модели)
+
+Открывает доступ ко всем локальным моделям: T-Pro 2.0, T-Lite, Qwen3, Llama, DeepSeek, Gemma, Phi, Home-3B.
+
+**Файлы:**
+- `const.py` — `ID_OLLAMA`, `UNIQUE_ID_OLLAMA`, модели, `CONF_BASE_URL`
+- `client_util.py` — `ChatOllama(model=..., base_url=...)`
+- `config_flow.py` — шаг `async_step_ollama` (base_url + model)
+- `manifest.json` — `langchain-ollama>=0.3.0`
+- `strings.json`, `translations/` — строки для Ollama
+
+**Config:**
+- `base_url` (по умолчанию `http://localhost:11434`)
+- `model` (текстовое поле, т.к. модели загружаются пользователем)
+
+#### 0.8.2 — DeepSeek
+
+Самый дешёвый cloud-провайдер. V3 для обычных задач, R1 для reasoning.
+
+**Файлы:**
+- `const.py` — `ID_DEEPSEEK`, модели (`deepseek-chat`, `deepseek-reasoner`)
+- `client_util.py` — `ChatDeepSeek(model=..., api_key=...)`
+- `config_flow.py` — шаг `async_step_deepseek`
+- `manifest.json` — `langchain-deepseek>=0.1.0`
+
+#### 0.8.3 — Anthropic (Claude)
+
+Для пользователей, которые хотят Claude через GigaChain.
+
+**Файлы:**
+- `const.py` — `ID_ANTHROPIC`, модели (`claude-sonnet-4-6`, `claude-haiku-4-5`)
+- `client_util.py` — `ChatAnthropic(model=..., api_key=...)`
+- `config_flow.py` — шаг `async_step_anthropic`
+- `manifest.json` — `langchain-anthropic>=0.3.0`
+
+---
+
+### v0.9 — Sub-entries (несколько агентов)
+
+**Приоритет:** Средний-высокий
+**Сложность:** Средняя
+**Зависимости:** v0.8 (больше пользы с несколькими провайдерами)
+
+**Что:**
+- Позволить создавать несколько conversation/AI task agents с разными моделями и промптами через одну интеграцию
+- Паттерн из HA 2025.8+ — все официальные интеграции перешли на sub-entries
+- Пример: "GigaChat Max для управления домом" + "GigaChat Lite для чата" + "DeepSeek R1 для аналитики"
+
+**Файлы:**
+- `config_flow.py` — переработка: корневая entry хранит credentials, sub-entries хранят модель/промпт/API
+- `__init__.py` — setup sub-entries
+- `conversation.py`, `ai_task.py` — привязка к sub-entry
+
+**Референсы:**
+- https://developers.home-assistant.io/docs/config_entries/subentries
+- `homeassistant.components.openai_conversation` (реализация через sub-entries)
+
+---
+
+## 3. Фаза 2 — Дифференциация (v1.0 – v1.3)
+
+Цель: добавить уникальные возможности, которых нет у большинства конкурентов.
+
+### v1.0 — Vision / мультимодальность
+
+**Приоритет:** Средний
+**Сложность:** Средняя
+**Зависимости:** v0.8 (нужны провайдеры с vision: GigaChat 2.0, OpenAI, Ollama)
+
+**Что:**
+- Отправка изображений с камер HA в LLM
+- Анализ: "Кто у двери?", "Что показывает камера во дворе?"
+- Поддержка: GigaChat 2.0 (мультимодальный), OpenAI GPT-4o/4.1, Ollama (LLaVA, Gemma Vision)
+
+**Реализация:**
+- Получение snapshot с камеры через `camera.async_get_image()`
+- Передача base64 изображения в LLM через LangChain `HumanMessage(content=[{"type": "image_url", ...}])`
+- Новый tool `get_camera_snapshot` или интеграция с Frigate events
+
+---
+
+### v1.1 — Генерация изображений (GigaChat Kandinsky + YandexART)
+
+**Приоритет:** Средний
+**Сложность:** Средняя
+**Зависимости:** нет
+
+**Что:**
+- GigaChat 2.0 имеет встроенную генерацию через Kandinsky
+- YandexGPT имеет YandexART API
+- Результат: `image` entity или сервис `gigachain.generate_image`
+
+**Реализация:**
+- Для GigaChat: уже поддерживается через API (модель сама решает, когда генерировать)
+- Для YandexART: отдельный API вызов
+- Сохранение результата в `/media/` или отправка через notify
+
+---
+
+### v1.2 — MCP (Model Context Protocol)
+
+**Приоритет:** Средний
+**Сложность:** Средняя-высокая
+**Зависимости:** v0.7 (Assist API)
+
+**Что:**
+- Подключение внешних MCP серверов как дополнительных tools для LLM
+- Все официальные интеграции HA поддерживают MCP с 2025.8
+- Примеры: новости, погода из внешних API, todo-листы, файловая система
+
+**Реализация:**
+- HA уже предоставляет MCP tools через `chat_log.llm_api.tools` — если пользователь настроил MCP в HA, tools автоматически доступны через Assist API
+- Дополнительно: собственный MCP client для LangChain tools (через `langchain-mcp`)
+
+---
+
+### v1.3 — Доступ к истории состояний
+
+**Приоритет:** Средний
+**Сложность:** Средняя
+**Зависимости:** v0.7 (tool calling)
+
+**Что:**
+- LLM может запрашивать историю состояний entity: "Какая температура была вчера?", "Когда последний раз открывали дверь?"
+- У Extended OpenAI Conversation это одна из ключевых фич
+
+**Реализация:**
+- Добавить custom tool `get_history(entity_id, start_time, end_time)`
+- Использовать `homeassistant.components.recorder` для получения данных
+- Форматирование результата в текст для LLM
+
+---
+
+## 4. Фаза 3 — Лидерство (v1.4+)
+
+Цель: уникальные фичи, которых нет ни у кого.
+
+### v1.4 — Multi-agent система
+
+**Приоритет:** Низкий
+**Сложность:** Высокая
+
+**Что:**
+- Dispatcher Agent маршрутизирует запросы между специализированными агентами
+- Агент управления устройствами (дешёвая быстрая модель)
+- Агент аналитики (reasoning модель)
+- Агент мультимедиа (vision модель)
+- Реализация через LangGraph
+
+---
+
+### v1.5 — Telegram-бот
+
+**Приоритет:** Низкий
+**Сложность:** Низкая
+
+**Что:**
+- Использование GigaChain как backend для Telegram-бота
+- Управление домом через Telegram
+- Отправка уведомлений с анализом камер
+
+---
+
+### v1.6 — STT/TTS интеграция
+
+**Приоритет:** Низкий
+**Сложность:** Средняя
+
+**Что:**
+- Связка с Yandex SpeechKit для STT/TTS на русском
+- GigaChat TTS (когда появится)
+- Полный voice pipeline: микрофон → STT → GigaChain → TTS → динамик
+
+---
+
+### v1.7 — Skill-система
+
+**Приоритет:** Низкий
+**Сложность:** Высокая
+
+**Что:**
+- Загружаемые "навыки" из директории (как у Extended OpenAI)
+- YAML-описание навыка: промпт + tools + trigger
+- Маркетплейс навыков (community-driven)
+
+---
+
+### v1.8 — Prompt caching
+
+**Приоритет:** Низкий
+**Сложность:** Низкая
+
+**Что:**
+- Кэширование системного промпта для ускорения повторных запросов
+- Экономия токенов при повторяющихся вызовах
+- Реализация: hash промпта → cached response для идентичных запросов
+
+---
+
+## 5. Технические детали по задачам
+
+### Зависимости для новых провайдеров
+
+| Провайдер | pip-пакет | LangChain класс | Min version |
+|-----------|-----------|-----------------|-------------|
+| Ollama | `langchain-ollama` | `ChatOllama` | >=0.3.0 |
+| DeepSeek | `langchain-deepseek` | `ChatDeepSeek` | >=0.1.0 |
+| Anthropic | `langchain-anthropic` | `ChatAnthropic` | >=0.3.0 |
+
+### Рекомендуемые локальные модели (для Ollama)
+
+| Модель | RAM | Лучше всего для | Язык |
+|--------|-----|-----------------|------|
+| Home-3B-v3 | ~2GB | Device control (97% точность) | EN |
+| T-Lite 7B | ~4GB | Русскоязычный чат | RU |
+| T-Pro 2.0 32B | ~18GB | Русский reasoning, tool calling | RU |
+| Qwen3 4B | ~3GB | Мультиязычный, tool calling | RU/EN/ZH |
+| Gemma 3 4B | ~3GB | Vision + чат | EN |
+
+### Целевые метрики по фазам
+
+| Фаза | Версия | Тестов | Провайдеров | Ключевая фича |
+|-------|--------|--------|-------------|---------------|
+| Текущая | 0.6.0 | 34 | 3 | Assist API |
+| Фаза 1 | 0.9.0 | ~60 | 6 | AI Task + Ollama + Sub-entries |
+| Фаза 2 | 1.3.0 | ~80 | 6 | Vision + MCP + Image Gen |
+| Фаза 3 | 1.8.0 | ~100 | 6+ | Multi-agent + Telegram + Skills |
+
+---
+
+```mermaid
+gantt
+ title GigaChain Roadmap 2026
+ dateFormat YYYY-MM
+ axisFormat %b %Y
+
+ section Фаза 1 — Паритет
+ v0.7 AI Task entity :a1, 2026-03, 2026-04
+ v0.8 Ollama + DeepSeek + Anthropic :a2, 2026-04, 2026-05
+ v0.9 Sub-entries :a3, 2026-05, 2026-06
+
+ section Фаза 2 — Дифференциация
+ v1.0 Vision :b1, 2026-06, 2026-07
+ v1.1 Image Generation :b2, 2026-07, 2026-08
+ v1.2 MCP :b3, 2026-07, 2026-08
+ v1.3 History Access :b4, 2026-08, 2026-09
+
+ section Фаза 3 — Лидерство
+ v1.4 Multi-agent :c1, 2026-09, 2026-11
+ v1.5 Telegram Bot :c2, 2026-10, 2026-11
+ v1.6 STT/TTS :c3, 2026-11, 2026-12
+ v1.7 Skill System :c4, 2026-12, 2027-02
+```
diff --git a/hacs.json b/hacs.json
index 797bcf4..1621fe2 100644
--- a/hacs.json
+++ b/hacs.json
@@ -1,4 +1,4 @@
{
- "name": "GigaChain",
- "render_readme" : true
+ "name": "SmartChain",
+ "render_readme": true
}
diff --git a/tests/conftest.py b/tests/conftest.py
index dee41d7..46f7230 100644
--- a/tests/conftest.py
+++ b/tests/conftest.py
@@ -1,4 +1,4 @@
-"""Fixtures for GigaChain tests."""
+"""Fixtures for SmartChain tests."""
from unittest.mock import AsyncMock, MagicMock, patch
@@ -8,7 +8,7 @@
from homeassistant.setup import async_setup_component
from langchain_core.messages import AIMessage, AIMessageChunk
-from custom_components.gigachain.const import (
+from custom_components.smartchain.const import (
CONF_API_KEY,
CONF_ENGINE,
DOMAIN,
@@ -75,7 +75,7 @@ def mock_config_entry():
def mock_validate_client():
"""Mock validate_client to skip actual API calls."""
with patch(
- "custom_components.gigachain.config_flow.validate_client",
+ "custom_components.smartchain.config_flow.validate_client",
new_callable=AsyncMock,
) as mock:
yield mock
@@ -85,7 +85,7 @@ def mock_validate_client():
def mock_get_client(mock_llm_client):
"""Mock get_client to return a fake LLM client."""
with patch(
- "custom_components.gigachain.get_client",
+ "custom_components.smartchain.get_client",
new_callable=AsyncMock,
return_value=mock_llm_client,
) as mock:
diff --git a/tests/test_config_flow.py b/tests/test_config_flow.py
index 62c280a..d53fe4b 100644
--- a/tests/test_config_flow.py
+++ b/tests/test_config_flow.py
@@ -1,4 +1,4 @@
-"""Tests for GigaChain config flow."""
+"""Tests for SmartChain config flow."""
from unittest.mock import AsyncMock, patch
@@ -9,7 +9,7 @@
from homeassistant.data_entry_flow import FlowResultType
from httpx import ConnectError
-from custom_components.gigachain.const import (
+from custom_components.smartchain.const import (
CONF_API_KEY,
CONF_ENGINE,
CONF_FOLDER_ID,
@@ -133,7 +133,7 @@ async def test_openai_full_flow(
async def test_gigachat_connect_error(hass: HomeAssistant) -> None:
"""Test GigaChat config flow handles connection error."""
with patch(
- "custom_components.gigachain.config_flow.validate_client",
+ "custom_components.smartchain.config_flow.validate_client",
side_effect=ConnectError("Connection failed"),
):
result = await hass.config_entries.flow.async_init(
@@ -153,7 +153,7 @@ async def test_gigachat_connect_error(hass: HomeAssistant) -> None:
async def test_gigachat_invalid_response(hass: HomeAssistant) -> None:
"""Test GigaChat config flow handles invalid response."""
with patch(
- "custom_components.gigachain.config_flow.validate_client",
+ "custom_components.smartchain.config_flow.validate_client",
side_effect=ResponseError("Unauthorized"),
):
result = await hass.config_entries.flow.async_init(
@@ -173,7 +173,7 @@ async def test_gigachat_invalid_response(hass: HomeAssistant) -> None:
async def test_gigachat_unknown_error(hass: HomeAssistant) -> None:
"""Test GigaChat config flow handles unknown error."""
with patch(
- "custom_components.gigachain.config_flow.validate_client",
+ "custom_components.smartchain.config_flow.validate_client",
side_effect=RuntimeError("Something unexpected"),
):
result = await hass.config_entries.flow.async_init(
@@ -195,7 +195,7 @@ async def test_skip_validation(
) -> None:
"""Test config flow with skip_validation=True skips API call."""
with patch(
- "custom_components.gigachain.config_flow.validate_client",
+ "custom_components.smartchain.config_flow.validate_client",
new_callable=AsyncMock,
) as mock_validate:
result = await hass.config_entries.flow.async_init(
diff --git a/tests/test_init.py b/tests/test_init.py
index 83c78a2..db9826f 100644
--- a/tests/test_init.py
+++ b/tests/test_init.py
@@ -1,5 +1,6 @@
-"""Tests for GigaChain conversation entity."""
+"""Tests for SmartChain conversation entity."""
+import json
from unittest.mock import AsyncMock, MagicMock, patch
import pytest
@@ -7,20 +8,29 @@
from homeassistant.components.conversation.chat_log import (
AssistantContent,
SystemContent,
+ ToolResultContent,
UserContent,
)
from homeassistant.core import Context, HomeAssistant
-from homeassistant.helpers import intent
-from langchain_core.messages import AIMessage, AIMessageChunk, HumanMessage, SystemMessage
+from homeassistant.helpers import intent, llm
+from langchain_core.messages import (
+ AIMessage,
+ AIMessageChunk,
+ HumanMessage,
+ SystemMessage,
+ ToolMessage,
+)
-from custom_components.gigachain.conversation import (
- GigaChainConversationEntity,
+from custom_components.smartchain.conversation import (
+ SmartChainConversationEntity,
_async_langchain_stream,
_chatlog_to_langchain,
+ _ha_tool_to_dict,
)
-from custom_components.gigachain.const import (
+from custom_components.smartchain.const import (
CONF_CHAT_HISTORY,
CONF_ENGINE,
+ CONF_LLM_HASS_API,
CONF_PROCESS_BUILTIN_SENTENCES,
CONF_PROMPT,
ID_GIGACHAT,
@@ -49,8 +59,9 @@ def _make_chat_log(conversation_id="test-conv-id", user_text="Hello, assistant!"
UserContent(content=user_text),
]
chat_log.async_add_assistant_content_without_tools = MagicMock()
+ chat_log.llm_api = None
+ chat_log.unresponded_tool_results = False
- # Support streaming: async_add_delta_content_stream collects deltas into AssistantContent
async def _mock_add_delta_stream(agent_id, stream):
collected = ""
async for delta in stream:
@@ -81,8 +92,8 @@ def mock_entry(mock_llm_client):
@pytest.fixture
def entity(hass: HomeAssistant, mock_entry):
- """Create a GigaChainConversationEntity."""
- ent = GigaChainConversationEntity(mock_entry)
+ """Create a SmartChainConversationEntity."""
+ ent = SmartChainConversationEntity(mock_entry)
ent.hass = hass
return ent
@@ -116,7 +127,6 @@ async def test_handle_message_sets_system_prompt(
"""Test that system prompt is set in ChatLog."""
await entity._async_handle_message(user_input, mock_chat_log)
- # content[0] should be replaced with the rendered system prompt
assert isinstance(mock_chat_log.content[0], SystemContent)
assert "test assistant" in mock_chat_log.content[0].content
@@ -127,7 +137,6 @@ async def test_handle_message_sends_correct_messages_to_llm(
"""Test that LLM receives correct LangChain messages from ChatLog."""
await entity._async_handle_message(user_input, mock_chat_log)
- # Check what was passed to client.astream
call_args = entity.entry.runtime_data.astream.call_args[0][0]
assert len(call_args) == 2 # system + human
assert isinstance(call_args[0], SystemMessage)
@@ -174,10 +183,9 @@ async def test_handle_message_history_disabled(
}
entry.runtime_data = mock_llm_client
- ent = GigaChainConversationEntity(entry)
+ ent = SmartChainConversationEntity(entry)
ent.hass = hass
- # ChatLog has history, but history is disabled
chat_log = _make_chat_log()
chat_log.content = [
SystemContent(content=""),
@@ -188,9 +196,8 @@ async def test_handle_message_history_disabled(
await ent._async_handle_message(user_input, chat_log)
- # Only system + current user message (not old history)
call_args = mock_llm_client.astream.call_args[0][0]
- assert len(call_args) == 2 # system + human (no history)
+ assert len(call_args) == 2
assert isinstance(call_args[0], SystemMessage)
assert isinstance(call_args[1], HumanMessage)
assert call_args[1].content == "Hello, assistant!"
@@ -230,12 +237,12 @@ async def test_handle_message_with_builtin_not_recognized(
mock_default_response = MagicMock(spec=ConversationResult)
mock_default_response.response = MagicMock()
- mock_default_response.response.intent = None # Not recognized
+ mock_default_response.response.intent = None
mock_default_agent = AsyncMock()
mock_default_agent.async_process.return_value = mock_default_response
- ent = GigaChainConversationEntity(entry)
+ ent = SmartChainConversationEntity(entry)
ent.hass = hass
with patch(
@@ -263,7 +270,7 @@ async def test_handle_message_builtin_recognized(
entry.runtime_data = mock_llm_client
mock_intent_response = MagicMock()
- mock_intent_response.intent = MagicMock() # Truthy = recognized
+ mock_intent_response.intent = MagicMock()
mock_intent_response.speech = {"plain": {"speech": "HA handled this"}}
mock_default_response = MagicMock(spec=ConversationResult)
@@ -272,7 +279,7 @@ async def test_handle_message_builtin_recognized(
mock_default_agent = AsyncMock()
mock_default_agent.async_process.return_value = mock_default_response
- ent = GigaChainConversationEntity(entry)
+ ent = SmartChainConversationEntity(entry)
ent.hass = hass
with patch(
@@ -333,7 +340,7 @@ def test_chatlog_to_langchain_skips_empty_assistant() -> None:
messages = _chatlog_to_langchain(chat_log)
- assert len(messages) == 2 # system + human (empty assistant skipped)
+ assert len(messages) == 2
async def test_async_langchain_stream() -> None:
@@ -369,8 +376,141 @@ async def _fake_astream(messages):
async for delta in _async_langchain_stream(client, []):
deltas.append(delta)
- # First chunk has role but no content — still yielded because it has "role"
- # Second chunk has content
assert len(deltas) == 2
assert deltas[0] == {"role": "assistant"}
assert deltas[1] == {"content": "data"}
+
+
+def test_chatlog_to_langchain_with_tool_calls() -> None:
+ """Test conversion of ChatLog with tool calls and tool results."""
+ tool_input = llm.ToolInput(
+ tool_name="HassTurnOn",
+ tool_args={"entity_id": "light.kitchen"},
+ id="call_123",
+ )
+ chat_log = MagicMock()
+ chat_log.content = [
+ SystemContent(content="System prompt"),
+ UserContent(content="Turn on kitchen light"),
+ AssistantContent(
+ agent_id="test",
+ content="",
+ tool_calls=[tool_input],
+ ),
+ ToolResultContent(
+ agent_id="test",
+ tool_call_id="call_123",
+ tool_name="HassTurnOn",
+ tool_result={"success": True},
+ ),
+ AssistantContent(agent_id="test", content="Done!"),
+ ]
+
+ messages = _chatlog_to_langchain(chat_log)
+
+ assert len(messages) == 5
+ assert isinstance(messages[0], SystemMessage)
+ assert isinstance(messages[1], HumanMessage)
+ assert isinstance(messages[2], AIMessage)
+ assert len(messages[2].tool_calls) == 1
+ assert messages[2].tool_calls[0]["name"] == "HassTurnOn"
+ assert messages[2].tool_calls[0]["id"] == "call_123"
+ assert isinstance(messages[3], ToolMessage)
+ assert messages[3].tool_call_id == "call_123"
+ assert json.loads(messages[3].content) == {"success": True}
+ assert isinstance(messages[4], AIMessage)
+ assert messages[4].content == "Done!"
+
+
+def test_ha_tool_to_dict() -> None:
+ """Test conversion of HA llm.Tool to dict for LangChain."""
+ import voluptuous as vol
+
+ class MockTool(llm.Tool):
+ name = "HassTurnOn"
+ description = "Turn on a device"
+ parameters = vol.Schema({
+ vol.Required("entity_id"): str,
+ })
+
+ async def async_call(self, hass, tool_input, llm_context):
+ return {"success": True}
+
+ tool = MockTool()
+ result = _ha_tool_to_dict(tool)
+
+ assert result["name"] == "HassTurnOn"
+ assert result["description"] == "Turn on a device"
+ assert "properties" in result["parameters"]
+ assert "entity_id" in result["parameters"]["properties"]
+
+
+async def test_async_langchain_stream_with_tool_calls() -> None:
+ """Test that tool_calls from LLM are converted to HA ToolInput in stream."""
+ client = MagicMock()
+
+ async def _fake_astream(messages):
+ yield AIMessageChunk(
+ content="",
+ tool_calls=[
+ {"id": "call_1", "name": "HassTurnOn", "args": {"entity_id": "light.kitchen"}},
+ ],
+ )
+
+ client.astream = _fake_astream
+
+ deltas = []
+ async for delta in _async_langchain_stream(client, []):
+ deltas.append(delta)
+
+ assert len(deltas) == 1
+ assert deltas[0]["role"] == "assistant"
+ assert "tool_calls" in deltas[0]
+ assert len(deltas[0]["tool_calls"]) == 1
+ tc = deltas[0]["tool_calls"][0]
+ assert isinstance(tc, llm.ToolInput)
+ assert tc.tool_name == "HassTurnOn"
+ assert tc.tool_args == {"entity_id": "light.kitchen"}
+ assert tc.id == "call_1"
+
+
+async def test_handle_message_with_llm_api(
+ hass: HomeAssistant, mock_llm_client, user_input
+) -> None:
+ """Test _async_handle_message with LLM Hass API configured."""
+ entry = MagicMock()
+ entry.entry_id = "test_entry"
+ entry.data = {CONF_ENGINE: ID_GIGACHAT, "api_key": "test"}
+ entry.options = {
+ CONF_PROMPT: "Test prompt.",
+ CONF_CHAT_HISTORY: True,
+ CONF_PROCESS_BUILTIN_SENTENCES: False,
+ CONF_LLM_HASS_API: "assist",
+ }
+ entry.runtime_data = mock_llm_client
+
+ ent = SmartChainConversationEntity(entry)
+ ent.hass = hass
+
+ chat_log = _make_chat_log()
+
+ with patch.object(
+ chat_log,
+ "async_provide_llm_data",
+ new_callable=AsyncMock,
+ ) as mock_provide:
+ chat_log.llm_api = None
+ await ent._async_handle_message(user_input, chat_log)
+
+ mock_provide.assert_called_once()
+ assert mock_provide.call_args[0][1] == "assist"
+
+
+async def test_handle_message_no_llm_api_sets_prompt_manually(
+ hass: HomeAssistant, entity, user_input, mock_chat_log
+) -> None:
+ """Test that without LLM API configured, system prompt is set manually."""
+ await entity._async_handle_message(user_input, mock_chat_log)
+
+ assert isinstance(mock_chat_log.content[0], SystemContent)
+ assert "test assistant" in mock_chat_log.content[0].content
diff --git a/tests/test_setup.py b/tests/test_setup.py
index 3405533..465da89 100644
--- a/tests/test_setup.py
+++ b/tests/test_setup.py
@@ -1,4 +1,4 @@
-"""Tests for GigaChain integration setup and unload."""
+"""Tests for SmartChain integration setup and unload."""
from unittest.mock import AsyncMock, MagicMock, patch
@@ -6,7 +6,7 @@
from homeassistant.core import HomeAssistant
from pytest_homeassistant_custom_component.common import MockConfigEntry
-from custom_components.gigachain.const import (
+from custom_components.smartchain.const import (
CONF_API_KEY,
CONF_ENGINE,
DOMAIN,
@@ -49,7 +49,7 @@ async def test_setup_entry_gigachat(
) -> None:
"""Test successful setup of GigaChat entry."""
with patch(
- "custom_components.gigachain.get_client",
+ "custom_components.smartchain.get_client",
new_callable=AsyncMock,
return_value=mock_llm_client,
):
@@ -65,7 +65,7 @@ async def test_setup_entry_openai(
) -> None:
"""Test successful setup of OpenAI entry."""
with patch(
- "custom_components.gigachain.get_client",
+ "custom_components.smartchain.get_client",
new_callable=AsyncMock,
return_value=mock_llm_client,
):
@@ -81,7 +81,7 @@ async def test_unload_entry(
) -> None:
"""Test unloading a config entry."""
with patch(
- "custom_components.gigachain.get_client",
+ "custom_components.smartchain.get_client",
new_callable=AsyncMock,
return_value=mock_llm_client,
):
@@ -99,16 +99,14 @@ async def test_setup_creates_conversation_entity(
) -> None:
"""Test that setup creates a conversation entity."""
with patch(
- "custom_components.gigachain.get_client",
+ "custom_components.smartchain.get_client",
new_callable=AsyncMock,
return_value=mock_llm_client,
):
await hass.config_entries.async_setup(mock_gigachat_entry.entry_id)
await hass.async_block_till_done()
- # Check that a conversation entity was created
states = [s for s in hass.states.async_all() if s.domain == "conversation"]
- # Should have default HA agent + our GigaChain entity
assert len(states) >= 2
entity_ids = [s.entity_id for s in states]
- assert any("gigachain" in eid for eid in entity_ids)
+ assert any("smartchain" in eid for eid in entity_ids)
From b52e915965599a071edba0c2ff090c173d91967f Mon Sep 17 00:00:00 2001
From: dzerik