homeassistant 2025.6.3__py3-none-any.whl → 2025.7.0b1__py3-none-any.whl

homeassistant/components/ai_task/__init__.py

@@ -0,0 +1,134 @@
+"""Integration to offer AI tasks to Home Assistant."""
+
+import logging
+
+import voluptuous as vol
+
+from homeassistant.config_entries import ConfigEntry
+from homeassistant.const import ATTR_ENTITY_ID
+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 (
+    ATTR_INSTRUCTIONS,
+    ATTR_TASK_NAME,
+    DATA_COMPONENT,
+    DATA_PREFERENCES,
+    DOMAIN,
+    SERVICE_GENERATE_DATA,
+    AITaskEntityFeature,
+)
+from .entity import AITaskEntity
+from .http import async_setup as async_setup_http
+from .task import GenDataTask, GenDataTaskResult, async_generate_data
+
+__all__ = [
+    "DOMAIN",
+    "AITaskEntity",
+    "AITaskEntityFeature",
+    "GenDataTask",
+    "GenDataTaskResult",
+    "async_generate_data",
+    "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_http(hass)
+    hass.services.async_register(
+        DOMAIN,
+        SERVICE_GENERATE_DATA,
+        async_service_generate_data,
+        schema=vol.Schema(
+            {
+                vol.Required(ATTR_TASK_NAME): cv.string,
+                vol.Optional(ATTR_ENTITY_ID): cv.entity_id,
+                vol.Required(ATTR_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_data(call: ServiceCall) -> ServiceResponse:
+    """Run the run task service."""
+    result = await async_generate_data(hass=call.hass, **call.data)
+    return result.as_dict()
+
+
+class AITaskPreferences:
+    """AI Task preferences."""
+
+    KEYS = ("gen_data_entity_id",)
+
+    gen_data_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_data_entity_id: str | None | UndefinedType = UNDEFINED,
+    ) -> None:
+        """Set the preferences."""
+        changed = False
+        for key, value in (("gen_data_entity_id", gen_data_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,34 @@
+"""Constants for the AI Task integration."""
+
+from __future__ import annotations
+
+from enum import IntFlag
+from typing import TYPE_CHECKING, Final
+
+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")
+
+SERVICE_GENERATE_DATA = "generate_data"
+
+ATTR_INSTRUCTIONS: Final = "instructions"
+ATTR_TASK_NAME: Final = "task_name"
+
+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_DATA = 1
+    """Generate data 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 GenDataTask, GenDataTaskResult
+
+
+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: GenDataTask,
+    ) -> 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_data(
+        self,
+        task: GenDataTask,
+    ) -> GenDataTaskResult:
+        """Run a gen data 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_data(task, chat_log)
+
+    async def _async_generate_data(
+        self,
+        task: GenDataTask,
+        chat_log: ChatLog,
+    ) -> GenDataTaskResult:
+        """Handle a gen data 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_data_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_data": {
+      "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_data:
+  fields:
+    task_name:
+      example: "home summary"
+      required: true
+      selector:
+        text:
+    instructions:
+      example: "Generate a funny notification that the garage door was left open"
+      required: true
+      selector:
+        text:
+    entity_id:
+      required: false
+      selector:
+        entity:
+          domain: ai_task
+          supported_features:
+            - ai_task.AITaskEntityFeature.GENERATE_DATA

homeassistant/components/ai_task/strings.json

@@ -0,0 +1,22 @@
+{
+  "services": {
+    "generate_data": {
+      "name": "Generate data",
+      "description": "Uses AI to run a task that generates data.",
+      "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."
+        }
+      }
+    }
+  }
+}

homeassistant/components/ai_task/task.py

@@ -0,0 +1,75 @@
+"""AI tasks to be handled by agents."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from homeassistant.core import HomeAssistant
+from homeassistant.exceptions import HomeAssistantError
+
+from .const import DATA_COMPONENT, DATA_PREFERENCES, AITaskEntityFeature
+
+
+async def async_generate_data(
+    hass: HomeAssistant,
+    *,
+    task_name: str,
+    entity_id: str | None = None,
+    instructions: str,
+) -> GenDataTaskResult:
+    """Run a task in the AI Task integration."""
+    if entity_id is None:
+        entity_id = hass.data[DATA_PREFERENCES].gen_data_entity_id
+
+    if entity_id is None:
+        raise HomeAssistantError("No entity_id provided and no preferred entity set")
+
+    entity = hass.data[DATA_COMPONENT].get_entity(entity_id)
+    if entity is None:
+        raise HomeAssistantError(f"AI Task entity {entity_id} not found")
+
+    if AITaskEntityFeature.GENERATE_DATA not in entity.supported_features:
+        raise HomeAssistantError(
+            f"AI Task entity {entity_id} does not support generating data"
+        )
+
+    return await entity.internal_async_generate_data(
+        GenDataTask(
+            name=task_name,
+            instructions=instructions,
+        )
+    )
+
+
+@dataclass(slots=True)
+class GenDataTask:
+    """Gen data task to be processed."""
+
+    name: str
+    """Name of the task."""
+
+    instructions: str
+    """Instructions on what needs to be done."""
+
+    def __str__(self) -> str:
+        """Return task as a string."""
+        return f"<GenDataTask {self.name}: {id(self)}>"
+
+
+@dataclass(slots=True)
+class GenDataTaskResult:
+    """Result of gen data task."""
+
+    conversation_id: str
+    """Unique identifier for the conversation."""
+
+    data: Any
+    """Data generated by the task."""
+
+    def as_dict(self) -> dict[str, Any]:
+        """Return result as a dict."""
+        return {
+            "conversation_id": self.conversation_id,
+            "data": self.data,
+        }

homeassistant/components/ai_task/translations/bg.json

@@ -0,0 +1 @@
+{}

homeassistant/components/ai_task/translations/cs.json

@@ -0,0 +1,22 @@
+{
+    "services": {
+        "generate_data": {
+            "description": "Pou\u017e\u00edv\u00e1 AI ke spu\u0161t\u011bn\u00ed \u00falohy, kter\u00e1 generuje data.",
+            "fields": {
+                "entity_id": {
+                    "description": "ID entity, na kter\u00e9 se m\u00e1 \u00faloha spustit. Pokud nen\u00ed zad\u00e1no, bude pou\u017eita preferovan\u00e1 entita.",
+                    "name": "ID entity"
+                },
+                "instructions": {
+                    "description": "Instrukce, co je t\u0159eba ud\u011blat.",
+                    "name": "Instrukce"
+                },
+                "task_name": {
+                    "description": "N\u00e1zev \u00fakolu.",
+                    "name": "N\u00e1zev \u00fakolu"
+                }
+            },
+            "name": "Vygenerovat data"
+        }
+    }
+}

homeassistant/components/ai_task/translations/de.json

@@ -0,0 +1,22 @@
+{
+    "services": {
+        "generate_data": {
+            "description": "Verwendet KI, um eine Aufgabe auszuf\u00fchren, die Daten generiert.",
+            "fields": {
+                "entity_id": {
+                    "description": "Entit\u00e4ts-ID, auf der die Aufgabe ausgef\u00fchrt werden soll. Falls nicht angegeben, wird die bevorzugte Entit\u00e4t verwendet.",
+                    "name": "Entit\u00e4ts-ID"
+                },
+                "instructions": {
+                    "description": "Anweisungen, was zu tun ist.",
+                    "name": "Anweisungen"
+                },
+                "task_name": {
+                    "description": "Name der Aufgabe.",
+                    "name": "Aufgabenname"
+                }
+            },
+            "name": "Daten generieren"
+        }
+    }
+}

homeassistant/components/ai_task/translations/el.json

@@ -0,0 +1,22 @@
+{
+    "services": {
+        "generate_data": {
+            "description": "\u03a7\u03c1\u03b7\u03c3\u03b9\u03bc\u03bf\u03c0\u03bf\u03b9\u03b5\u03af \u03a4\u03b5\u03c7\u03bd\u03b7\u03c4\u03ae \u039d\u03bf\u03b7\u03bc\u03bf\u03c3\u03cd\u03bd\u03b7 \u03b3\u03b9\u03b1 \u03c4\u03b7\u03bd \u03b5\u03ba\u03c4\u03ad\u03bb\u03b5\u03c3\u03b7 \u03bc\u03b9\u03b1\u03c2 \u03b5\u03c1\u03b3\u03b1\u03c3\u03af\u03b1\u03c2 \u03c0\u03bf\u03c5 \u03c0\u03b1\u03c1\u03ac\u03b3\u03b5\u03b9 \u03b4\u03b5\u03b4\u03bf\u03bc\u03ad\u03bd\u03b1.",
+            "fields": {
+                "entity_id": {
+                    "description": "ID \u03bf\u03bd\u03c4\u03cc\u03c4\u03b7\u03c4\u03b1\u03c2 \u03b3\u03b9\u03b1 \u03c4\u03b7\u03bd \u03b5\u03ba\u03c4\u03ad\u03bb\u03b5\u03c3\u03b7 \u03c4\u03b7\u03c2 \u03b5\u03c1\u03b3\u03b1\u03c3\u03af\u03b1\u03c2. \u0395\u03ac\u03bd \u03b4\u03b5\u03bd \u03b4\u03bf\u03b8\u03b5\u03af, \u03b8\u03b1 \u03c7\u03c1\u03b7\u03c3\u03b9\u03bc\u03bf\u03c0\u03bf\u03b9\u03b7\u03b8\u03b5\u03af \u03b7 \u03c0\u03c1\u03bf\u03c4\u03b9\u03bc\u03ce\u03bc\u03b5\u03bd\u03b7 \u03bf\u03bd\u03c4\u03cc\u03c4\u03b7\u03c4\u03b1.",
+                    "name": "ID \u03bf\u03bd\u03c4\u03cc\u03c4\u03b7\u03c4\u03b1\u03c2"
+                },
+                "instructions": {
+                    "description": "\u039f\u03b4\u03b7\u03b3\u03af\u03b5\u03c2 \u03b3\u03b9\u03b1 \u03c4\u03bf \u03c4\u03b9 \u03c0\u03c1\u03ad\u03c0\u03b5\u03b9 \u03bd\u03b1 \u03b3\u03af\u03bd\u03b5\u03b9.",
+                    "name": "\u039f\u03b4\u03b7\u03b3\u03af\u03b5\u03c2"
+                },
+                "task_name": {
+                    "description": "\u039f\u03bd\u03bf\u03bc\u03b1 \u03c4\u03b7\u03c2 \u03b5\u03c1\u03b3\u03b1\u03c3\u03af\u03b1\u03c2.",
+                    "name": "\u039f\u03bd\u03bf\u03bc\u03b1 \u03b5\u03c1\u03b3\u03b1\u03c3\u03af\u03b1\u03c2"
+                }
+            },
+            "name": "\u0394\u03b7\u03bc\u03b9\u03bf\u03c5\u03c1\u03b3\u03af\u03b1 \u03b4\u03b5\u03b4\u03bf\u03bc\u03ad\u03bd\u03c9\u03bd"
+        }
+    }
+}

homeassistant/components/ai_task/translations/en.json

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

homeassistant/components/ai_task/translations/es.json

@@ -0,0 +1,22 @@
+{
+    "services": {
+        "generate_data": {
+            "description": "Utiliza IA para ejecutar una tarea que genera datos.",
+            "fields": {
+                "entity_id": {
+                    "description": "ID de entidad donde se ejecutar\u00e1 la tarea. Si no se proporciona, se utilizar\u00e1 la entidad preferida.",
+                    "name": "ID de entidad"
+                },
+                "instructions": {
+                    "description": "Instrucciones sobre lo que debe hacerse.",
+                    "name": "Instrucciones"
+                },
+                "task_name": {
+                    "description": "Nombre de la tarea.",
+                    "name": "Nombre de la tarea"
+                }
+            },
+            "name": "Generar datos"
+        }
+    }
+}

homeassistant/components/ai_task/translations/et.json

@@ -0,0 +1,22 @@
+{
+    "services": {
+        "generate_data": {
+            "description": "Kasutab tehisintellekti andmeid genereeriva \u00fclesande k\u00e4ivitamiseks.",
+            "fields": {
+                "entity_id": {
+                    "description": "Olemi ID millega \u00fclesanne k\u00e4ivitada. Kui seda ei esitata, kasutatakse eelistatud \u00fcksust.",
+                    "name": "Olemi ID"
+                },
+                "instructions": {
+                    "description": "Juhised selle kohta mida on vaja teha.",
+                    "name": "Juhised"
+                },
+                "task_name": {
+                    "description": "\u00dclesande nimi.",
+                    "name": "\u00dclesande nimi"
+                }
+            },
+            "name": "Andmete genereerimine"
+        }
+    }
+}

homeassistant/components/ai_task/translations/fr.json

@@ -0,0 +1 @@
+{}

homeassistant/components/ai_task/translations/ga.json

@@ -0,0 +1 @@
+{}

homeassistant/components/ai_task/translations/lt.json

@@ -0,0 +1,22 @@
+{
+    "services": {
+        "generate_data": {
+            "description": "Naudoja dirbtin\u012f intelekt\u0105 u\u017eduo\u010diai, kuri generuoja duomenis, atlikti.",
+            "fields": {
+                "entity_id": {
+                    "description": "Subjekto ID, kuriame bus vykdoma u\u017eduotis. Jei nepateikta, bus naudojamas pageidaujamas subjektas.",
+                    "name": "Subjekto ID"
+                },
+                "instructions": {
+                    "description": "Nurodymai, k\u0105 reikia daryti.",
+                    "name": "Instrukcijos"
+                },
+                "task_name": {
+                    "description": "U\u017eduoties pavadinimas.",
+                    "name": "U\u017eduoties pavadinimas"
+                }
+            },
+            "name": "Duomen\u0173 generavimas"
+        }
+    }
+}

homeassistant/components/ai_task/translations/nl.json

@@ -0,0 +1 @@
+{}

homeassistant/components/ai_task/translations/pt.json

@@ -0,0 +1,22 @@
+{
+    "services": {
+        "generate_data": {
+            "description": "Utiliza a IA para executar uma tarefa que gera dados.",
+            "fields": {
+                "entity_id": {
+                    "description": "ID da entidade para executar a tarefa. Se n\u00e3o for fornecida, ser\u00e1 utilizada a entidade preferida.",
+                    "name": "ID da Entidade"
+                },
+                "instructions": {
+                    "description": "Instru\u00e7\u00f5es sobre o que deve ser feito.",
+                    "name": "Instru\u00e7\u00f5es"
+                },
+                "task_name": {
+                    "description": "Nome da tarefa.",
+                    "name": "Nome da tarefa"
+                }
+            },
+            "name": "Gerar dados"
+        }
+    }
+}