[pull] dev from home-assistant:dev

homeassistant/components/ai_task/__init__.py

@@ -0,0 +1,125 @@
+"""Integration to offer AI tasks to Home Assistant."""
+
+import logging
+
+import voluptuous as vol
+
+from homeassistant.config_entries import ConfigEntry
+from homeassistant.core import (
+    HassJobType,
+    HomeAssistant,
+    ServiceCall,
+    ServiceResponse,
+    SupportsResponse,
+    callback,
+)
+from homeassistant.helpers import config_validation as cv, storage
+from homeassistant.helpers.entity_component import EntityComponent
+from homeassistant.helpers.typing import UNDEFINED, ConfigType, UndefinedType
+
+from .const import DATA_COMPONENT, DATA_PREFERENCES, DOMAIN, AITaskEntityFeature
+from .entity import AITaskEntity
+from .http import async_setup as async_setup_conversation_http
+from .task import GenTextTask, GenTextTaskResult, async_generate_text
+
+__all__ = [
+    "DOMAIN",
+    "AITaskEntity",
+    "AITaskEntityFeature",
+    "GenTextTask",
+    "GenTextTaskResult",
+    "async_generate_text",
+    "async_setup",
+    "async_setup_entry",
+    "async_unload_entry",
+]
+
+_LOGGER = logging.getLogger(__name__)
+
+CONFIG_SCHEMA = cv.config_entry_only_config_schema(DOMAIN)
+
+
+async def async_setup(hass: HomeAssistant, config: ConfigType) -> bool:
+    """Register the process service."""
+    entity_component = EntityComponent[AITaskEntity](_LOGGER, DOMAIN, hass)
+    hass.data[DATA_COMPONENT] = entity_component
+    hass.data[DATA_PREFERENCES] = AITaskPreferences(hass)
+    await hass.data[DATA_PREFERENCES].async_load()
+    async_setup_conversation_http(hass)
+    hass.services.async_register(
+        DOMAIN,
+        "generate_text",
+        async_service_generate_text,
+        schema=vol.Schema(
+            {
+                vol.Required("task_name"): cv.string,
+                vol.Optional("entity_id"): cv.entity_id,
+                vol.Required("instructions"): cv.string,
+            }
+        ),
+        supports_response=SupportsResponse.ONLY,
+        job_type=HassJobType.Coroutinefunction,
+    )
+    return True
+
+
+async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
+    """Set up a config entry."""
+    return await hass.data[DATA_COMPONENT].async_setup_entry(entry)
+
+
+async def async_unload_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
+    """Unload a config entry."""
+    return await hass.data[DATA_COMPONENT].async_unload_entry(entry)
+
+
+async def async_service_generate_text(call: ServiceCall) -> ServiceResponse:
+    """Run the run task service."""
+    result = await async_generate_text(hass=call.hass, **call.data)
+    return result.as_dict()  # type: ignore[return-value]
+
+
+class AITaskPreferences:
+    """AI Task preferences."""
+
+    KEYS = ("gen_text_entity_id",)
+
+    gen_text_entity_id: str | None = None
+
+    def __init__(self, hass: HomeAssistant) -> None:
+        """Initialize the preferences."""
+        self._store: storage.Store[dict[str, str | None]] = storage.Store(
+            hass, 1, DOMAIN
+        )
+
+    async def async_load(self) -> None:
+        """Load the data from the store."""
+        data = await self._store.async_load()
+        if data is None:
+            return
+        for key in self.KEYS:
+            setattr(self, key, data[key])
+
+    @callback
+    def async_set_preferences(
+        self,
+        *,
+        gen_text_entity_id: str | None | UndefinedType = UNDEFINED,
+    ) -> None:
+        """Set the preferences."""
+        changed = False
+        for key, value in (("gen_text_entity_id", gen_text_entity_id),):
+            if value is not UNDEFINED:
+                if getattr(self, key) != value:
+                    setattr(self, key, value)
+                    changed = True
+
+        if not changed:
+            return
+
+        self._store.async_delay_save(self.as_dict, 10)
+
+    @callback
+    def as_dict(self) -> dict[str, str | None]:
+        """Get the current preferences."""
+        return {key: getattr(self, key) for key in self.KEYS}

homeassistant/components/ai_task/const.py

@@ -0,0 +1,29 @@
+"""Constants for the AI Task integration."""
+
+from __future__ import annotations
+
+from enum import IntFlag
+from typing import TYPE_CHECKING
+
+from homeassistant.util.hass_dict import HassKey
+
+if TYPE_CHECKING:
+    from homeassistant.helpers.entity_component import EntityComponent
+
+    from . import AITaskPreferences
+    from .entity import AITaskEntity
+
+DOMAIN = "ai_task"
+DATA_COMPONENT: HassKey[EntityComponent[AITaskEntity]] = HassKey(DOMAIN)
+DATA_PREFERENCES: HassKey[AITaskPreferences] = HassKey(f"{DOMAIN}_preferences")
+
+DEFAULT_SYSTEM_PROMPT = (
+    "You are a Home Assistant expert and help users with their tasks."
+)
+
+
+class AITaskEntityFeature(IntFlag):
+    """Supported features of the AI task entity."""
+
+    GENERATE_TEXT = 1
+    """Generate text based on instructions."""

homeassistant/components/ai_task/entity.py

@@ -0,0 +1,103 @@
+"""Entity for the AI Task integration."""
+
+from collections.abc import AsyncGenerator
+import contextlib
+from typing import final
+
+from propcache.api import cached_property
+
+from homeassistant.components.conversation import (
+    ChatLog,
+    UserContent,
+    async_get_chat_log,
+)
+from homeassistant.const import STATE_UNAVAILABLE, STATE_UNKNOWN
+from homeassistant.helpers import llm
+from homeassistant.helpers.chat_session import async_get_chat_session
+from homeassistant.helpers.restore_state import RestoreEntity
+from homeassistant.util import dt as dt_util
+
+from .const import DEFAULT_SYSTEM_PROMPT, DOMAIN, AITaskEntityFeature
+from .task import GenTextTask, GenTextTaskResult
+
+
+class AITaskEntity(RestoreEntity):
+    """Entity that supports conversations."""
+
+    _attr_should_poll = False
+    _attr_supported_features = AITaskEntityFeature(0)
+    __last_activity: str | None = None
+
+    @property
+    @final
+    def state(self) -> str | None:
+        """Return the state of the entity."""
+        if self.__last_activity is None:
+            return None
+        return self.__last_activity
+
+    @cached_property
+    def supported_features(self) -> AITaskEntityFeature:
+        """Flag supported features."""
+        return self._attr_supported_features
+
+    async def async_internal_added_to_hass(self) -> None:
+        """Call when the entity is added to hass."""
+        await super().async_internal_added_to_hass()
+        state = await self.async_get_last_state()
+        if (
+            state is not None
+            and state.state is not None
+            and state.state not in (STATE_UNAVAILABLE, STATE_UNKNOWN)
+        ):
+            self.__last_activity = state.state
+
+    @final
+    @contextlib.asynccontextmanager
+    async def _async_get_ai_task_chat_log(
+        self,
+        task: GenTextTask,
+    ) -> AsyncGenerator[ChatLog]:
+        """Context manager used to manage the ChatLog used during an AI Task."""
+        # pylint: disable-next=contextmanager-generator-missing-cleanup
+        with (
+            async_get_chat_session(self.hass) as session,
+            async_get_chat_log(
+                self.hass,
+                session,
+                None,
+            ) as chat_log,
+        ):
+            await chat_log.async_provide_llm_data(
+                llm.LLMContext(
+                    platform=self.platform.domain,
+                    context=None,
+                    language=None,
+                    assistant=DOMAIN,
+                    device_id=None,
+                ),
+                user_llm_prompt=DEFAULT_SYSTEM_PROMPT,
+            )
+
+            chat_log.async_add_user_content(UserContent(task.instructions))
+
+            yield chat_log
+
+    @final
+    async def internal_async_generate_text(
+        self,
+        task: GenTextTask,
+    ) -> GenTextTaskResult:
+        """Run a gen text task."""
+        self.__last_activity = dt_util.utcnow().isoformat()
+        self.async_write_ha_state()
+        async with self._async_get_ai_task_chat_log(task) as chat_log:
+            return await self._async_generate_text(task, chat_log)
+
+    async def _async_generate_text(
+        self,
+        task: GenTextTask,
+        chat_log: ChatLog,
+    ) -> GenTextTaskResult:
+        """Handle a gen text task."""
+        raise NotImplementedError

homeassistant/components/ai_task/http.py

@@ -0,0 +1,54 @@
+"""HTTP endpoint for AI Task integration."""
+
+from typing import Any
+
+import voluptuous as vol
+
+from homeassistant.components import websocket_api
+from homeassistant.core import HomeAssistant, callback
+
+from .const import DATA_PREFERENCES
+
+
+@callback
+def async_setup(hass: HomeAssistant) -> None:
+    """Set up the HTTP API for the conversation integration."""
+    websocket_api.async_register_command(hass, websocket_get_preferences)
+    websocket_api.async_register_command(hass, websocket_set_preferences)
+
+
+@websocket_api.websocket_command(
+    {
+        vol.Required("type"): "ai_task/preferences/get",
+    }
+)
+@callback
+def websocket_get_preferences(
+    hass: HomeAssistant,
+    connection: websocket_api.ActiveConnection,
+    msg: dict[str, Any],
+) -> None:
+    """Get AI task preferences."""
+    preferences = hass.data[DATA_PREFERENCES]
+    connection.send_result(msg["id"], preferences.as_dict())
+
+
+@websocket_api.websocket_command(
+    {
+        vol.Required("type"): "ai_task/preferences/set",
+        vol.Optional("gen_text_entity_id"): vol.Any(str, None),
+    }
+)
+@websocket_api.require_admin
+@callback
+def websocket_set_preferences(
+    hass: HomeAssistant,
+    connection: websocket_api.ActiveConnection,
+    msg: dict[str, Any],
+) -> None:
+    """Set AI task preferences."""
+    preferences = hass.data[DATA_PREFERENCES]
+    msg.pop("type")
+    msg_id = msg.pop("id")
+    preferences.async_set_preferences(**msg)
+    connection.send_result(msg_id, preferences.as_dict())

homeassistant/components/ai_task/icons.json

@@ -0,0 +1,7 @@
+{
+  "services": {
+    "generate_text": {
+      "service": "mdi:file-star-four-points-outline"
+    }
+  }
+}

homeassistant/components/ai_task/manifest.json

@@ -0,0 +1,9 @@
+{
+  "domain": "ai_task",
+  "name": "AI Task",
+  "codeowners": ["@home-assistant/core"],
+  "dependencies": ["conversation"],
+  "documentation": "https://www.home-assistant.io/integrations/ai_task",
+  "integration_type": "system",
+  "quality_scale": "internal"
+}

homeassistant/components/ai_task/services.yaml

@@ -0,0 +1,19 @@
+generate_text:
+  fields:
+    task_name:
+      example: "home summary"
+      required: true
+      selector:
+        text:
+    instructions:
+      example: "Generate a funny notification that garage door was left open"
+      required: true
+      selector:
+        text:
+    entity_id:
+      required: false
+      selector:
+        entity:
+          domain: ai_task
+          supported_features:
+            - ai_task.AITaskEntityFeature.GENERATE_TEXT

homeassistant/components/ai_task/strings.json

@@ -0,0 +1,22 @@
+{
+  "services": {
+    "generate_text": {
+      "name": "Generate text",
+      "description": "Use AI to run a task that generates text.",
+      "fields": {
+        "task_name": {
+          "name": "Task Name",
+          "description": "Name of the task."
+        },
+        "instructions": {
+          "name": "Instructions",
+          "description": "Instructions on what needs to be done."
+        },
+        "entity_id": {
+          "name": "Entity ID",
+          "description": "Entity ID to run the task on. If not provided, the preferred entity will be used."
+        }
+      }
+    }
+  }
+}