homeassistant 2025.8.2__py3-none-any.whl → 2025.9.0__py3-none-any.whl

homeassistant/components/ai_task/const.py

@@ -12,12 +12,18 @@ if TYPE_CHECKING:
 
     from . import AITaskPreferences
     from .entity import AITaskEntity
+    from .task import ImageData
 
 DOMAIN = "ai_task"
 DATA_COMPONENT: HassKey[EntityComponent[AITaskEntity]] = HassKey(DOMAIN)
 DATA_PREFERENCES: HassKey[AITaskPreferences] = HassKey(f"{DOMAIN}_preferences")
+DATA_IMAGES: HassKey[dict[str, ImageData]] = HassKey(f"{DOMAIN}_images")
+
+IMAGE_EXPIRY_TIME = 60 * 60  # 1 hour
+MAX_IMAGES = 20
 
 SERVICE_GENERATE_DATA = "generate_data"
+SERVICE_GENERATE_IMAGE = "generate_image"
 
 ATTR_INSTRUCTIONS: Final = "instructions"
 ATTR_TASK_NAME: Final = "task_name"
@@ -38,3 +44,6 @@ class AITaskEntityFeature(IntFlag):
 
     SUPPORT_ATTACHMENTS = 2
     """Support attachments with generate data."""
+
+    GENERATE_IMAGE = 4
+    """Generate images based on instructions."""

homeassistant/components/ai_task/entity.py

@@ -18,7 +18,7 @@ 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
+from .task import GenDataTask, GenDataTaskResult, GenImageTask, GenImageTaskResult
 
 
 class AITaskEntity(RestoreEntity):
@@ -57,7 +57,7 @@ class AITaskEntity(RestoreEntity):
     async def _async_get_ai_task_chat_log(
         self,
         session: ChatSession,
-        task: GenDataTask,
+        task: GenDataTask | GenImageTask,
     ) -> AsyncGenerator[ChatLog]:
         """Context manager used to manage the ChatLog used during an AI Task."""
         # pylint: disable-next=contextmanager-generator-missing-cleanup
@@ -104,3 +104,23 @@ class AITaskEntity(RestoreEntity):
     ) -> GenDataTaskResult:
         """Handle a gen data task."""
         raise NotImplementedError
+
+    @final
+    async def internal_async_generate_image(
+        self,
+        session: ChatSession,
+        task: GenImageTask,
+    ) -> GenImageTaskResult:
+        """Run a gen image task."""
+        self.__last_activity = dt_util.utcnow().isoformat()
+        self.async_write_ha_state()
+        async with self._async_get_ai_task_chat_log(session, task) as chat_log:
+            return await self._async_generate_image(task, chat_log)
+
+    async def _async_generate_image(
+        self,
+        task: GenImageTask,
+        chat_log: ChatLog,
+    ) -> GenImageTaskResult:
+        """Handle a gen image task."""
+        raise NotImplementedError

homeassistant/components/ai_task/icons.json

@@ -1,7 +1,15 @@
 {
+  "entity_component": {
+    "_": {
+      "default": "mdi:star-four-points"
+    }
+  },
   "services": {
     "generate_data": {
       "service": "mdi:file-star-four-points-outline"
+    },
+    "generate_image": {
+      "service": "mdi:star-four-points-box-outline"
     }
   }
 }

homeassistant/components/ai_task/manifest.json

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

homeassistant/components/ai_task/media_source.py

@@ -0,0 +1,81 @@
+"""Expose images as media sources."""
+
+from __future__ import annotations
+
+import logging
+
+from homeassistant.components.media_player import BrowseError, MediaClass
+from homeassistant.components.media_source import (
+    BrowseMediaSource,
+    MediaSource,
+    MediaSourceItem,
+    PlayMedia,
+    Unresolvable,
+)
+from homeassistant.core import HomeAssistant
+
+from .const import DATA_IMAGES, DOMAIN
+
+_LOGGER = logging.getLogger(__name__)
+
+
+async def async_get_media_source(hass: HomeAssistant) -> ImageMediaSource:
+    """Set up image media source."""
+    _LOGGER.debug("Setting up image media source")
+    return ImageMediaSource(hass)
+
+
+class ImageMediaSource(MediaSource):
+    """Provide images as media sources."""
+
+    name: str = "AI Generated Images"
+
+    def __init__(self, hass: HomeAssistant) -> None:
+        """Initialize ImageMediaSource."""
+        super().__init__(DOMAIN)
+        self.hass = hass
+
+    async def async_resolve_media(self, item: MediaSourceItem) -> PlayMedia:
+        """Resolve media to a url."""
+        image_storage = self.hass.data[DATA_IMAGES]
+        image = image_storage.get(item.identifier)
+
+        if image is None:
+            raise Unresolvable(f"Could not resolve media item: {item.identifier}")
+
+        return PlayMedia(f"/api/{DOMAIN}/images/{item.identifier}", image.mime_type)
+
+    async def async_browse_media(
+        self,
+        item: MediaSourceItem,
+    ) -> BrowseMediaSource:
+        """Return media."""
+        if item.identifier:
+            raise BrowseError("Unknown item")
+
+        image_storage = self.hass.data[DATA_IMAGES]
+
+        children = [
+            BrowseMediaSource(
+                domain=DOMAIN,
+                identifier=filename,
+                media_class=MediaClass.IMAGE,
+                media_content_type=image.mime_type,
+                title=image.title or filename,
+                can_play=True,
+                can_expand=False,
+            )
+            for filename, image in image_storage.items()
+        ]
+
+        return BrowseMediaSource(
+            domain=DOMAIN,
+            identifier=None,
+            media_class=MediaClass.APP,
+            media_content_type="",
+            title="AI Generated Images",
+            can_play=False,
+            can_expand=True,
+            children_media_class=MediaClass.IMAGE,
+            children=children,
+        )

homeassistant/components/ai_task/services.yaml

@@ -20,7 +20,6 @@ generate_data:
             supported_features:
               - ai_task.AITaskEntityFeature.GENERATE_DATA
     structure:
-      advanced: true
       required: false
       example: '{ "name": { "selector": { "text": }, "description": "Name of the user", "required": "True" } } }, "age": { "selector": { "number": }, "description": "Age of the user" } }'
       selector:
@@ -31,3 +30,30 @@ generate_data:
         media:
           accept:
             - "*"
+generate_image:
+  fields:
+    task_name:
+      example: "picture of a dog"
+      required: true
+      selector:
+        text:
+    instructions:
+      example: "Generate a high quality square image of a dog on transparent background"
+      required: true
+      selector:
+        text:
+          multiline: true
+    entity_id:
+      required: true
+      selector:
+        entity:
+          filter:
+            domain: ai_task
+            supported_features:
+              - ai_task.AITaskEntityFeature.GENERATE_IMAGE
+    attachments:
+      required: false
+      selector:
+        media:
+          accept:
+            - "*"

homeassistant/components/ai_task/strings.json

@@ -25,6 +25,28 @@
           "description": "List of files to attach for multi-modal AI analysis."
         }
       }
+    },
+    "generate_image": {
+      "name": "Generate image",
+      "description": "Uses AI to generate image.",
+      "fields": {
+        "task_name": {
+          "name": "Task name",
+          "description": "Name of the task."
+        },
+        "instructions": {
+          "name": "Instructions",
+          "description": "Instructions that explains the image to be generated."
+        },
+        "entity_id": {
+          "name": "Entity ID",
+          "description": "Entity ID to run the task on."
+        },
+        "attachments": {
+          "name": "Attachments",
+          "description": "List of files to attach for using as references."
+        }
+      }
     }
   }
 }

homeassistant/components/ai_task/task.py

@@ -3,6 +3,8 @@
 from __future__ import annotations
 
 from dataclasses import dataclass
+from datetime import datetime
+from functools import partial
 import mimetypes
 from pathlib import Path
 import tempfile
@@ -11,11 +13,22 @@ from typing import Any
 import voluptuous as vol
 
 from homeassistant.components import camera, conversation, media_source
-from homeassistant.core import HomeAssistant, callback
+from homeassistant.core import HomeAssistant, ServiceResponse, callback
 from homeassistant.exceptions import HomeAssistantError
-from homeassistant.helpers.chat_session import async_get_chat_session
-
-from .const import DATA_COMPONENT, DATA_PREFERENCES, AITaskEntityFeature
+from homeassistant.helpers.chat_session import ChatSession, async_get_chat_session
+from homeassistant.helpers.event import async_call_later
+from homeassistant.helpers.network import get_url
+from homeassistant.util import RE_SANITIZE_FILENAME, slugify
+
+from .const import (
+    DATA_COMPONENT,
+    DATA_IMAGES,
+    DATA_PREFERENCES,
+    DOMAIN,
+    IMAGE_EXPIRY_TIME,
+    MAX_IMAGES,
+    AITaskEntityFeature,
+)
 
 
 def _save_camera_snapshot(image: camera.Image) -> Path:
@@ -29,43 +42,15 @@ def _save_camera_snapshot(image: camera.Image) -> Path:
         return Path(temp_file.name)
 
 
-async def async_generate_data(
+async def _resolve_attachments(
     hass: HomeAssistant,
-    *,
-    task_name: str,
-    entity_id: str | None = None,
-    instructions: str,
-    structure: vol.Schema | None = None,
+    session: ChatSession,
     attachments: list[dict] | None = None,
-) -> 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"
-        )
-
-    # Resolve attachments
+) -> list[conversation.Attachment]:
+    """Resolve attachments for a task."""
     resolved_attachments: list[conversation.Attachment] = []
     created_files: list[Path] = []
 
-    if (
-        attachments
-        and AITaskEntityFeature.SUPPORT_ATTACHMENTS not in entity.supported_features
-    ):
-        raise HomeAssistantError(
-            f"AI Task entity {entity_id} does not support attachments"
-        )
-
     for attachment in attachments or []:
         media_content_id = attachment["media_content_id"]
 
@@ -104,20 +89,59 @@ async def async_generate_data(
                 )
             )
 
-    with async_get_chat_session(hass) as session:
-        if created_files:
+    if not created_files:
+        return resolved_attachments
+
+    def cleanup_files() -> None:
+        """Cleanup temporary files."""
+        for file in created_files:
+            file.unlink(missing_ok=True)
 
-            def cleanup_files() -> None:
-                """Cleanup temporary files."""
-                for file in created_files:
-                    file.unlink(missing_ok=True)
+    @callback
+    def cleanup_files_callback() -> None:
+        """Cleanup temporary files."""
+        hass.async_add_executor_job(cleanup_files)
 
-            @callback
-            def cleanup_files_callback() -> None:
-                """Cleanup temporary files."""
-                hass.async_add_executor_job(cleanup_files)
+    session.async_on_cleanup(cleanup_files_callback)
 
-            session.async_on_cleanup(cleanup_files_callback)
+    return resolved_attachments
+
+
+async def async_generate_data(
+    hass: HomeAssistant,
+    *,
+    task_name: str,
+    entity_id: str | None = None,
+    instructions: str,
+    structure: vol.Schema | None = None,
+    attachments: list[dict] | None = None,
+) -> GenDataTaskResult:
+    """Run a data generation 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"
+        )
+
+    if (
+        attachments
+        and AITaskEntityFeature.SUPPORT_ATTACHMENTS not in entity.supported_features
+    ):
+        raise HomeAssistantError(
+            f"AI Task entity {entity_id} does not support attachments"
+        )
+
+    with async_get_chat_session(hass) as session:
+        resolved_attachments = await _resolve_attachments(hass, session, attachments)
 
         return await entity.internal_async_generate_data(
             session,
@@ -130,6 +154,97 @@ async def async_generate_data(
         )
 
 
+def _cleanup_images(image_storage: dict[str, ImageData], num_to_remove: int) -> None:
+    """Remove old images to keep the storage size under the limit."""
+    if num_to_remove <= 0:
+        return
+
+    if num_to_remove >= len(image_storage):
+        image_storage.clear()
+        return
+
+    sorted_images = sorted(
+        image_storage.items(),
+        key=lambda item: item[1].timestamp,
+    )
+
+    for filename, _ in sorted_images[:num_to_remove]:
+        image_storage.pop(filename, None)
+
+
+async def async_generate_image(
+    hass: HomeAssistant,
+    *,
+    task_name: str,
+    entity_id: str,
+    instructions: str,
+    attachments: list[dict] | None = None,
+) -> ServiceResponse:
+    """Run an image generation task in the AI Task integration."""
+    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_IMAGE not in entity.supported_features:
+        raise HomeAssistantError(
+            f"AI Task entity {entity_id} does not support generating images"
+        )
+
+    if (
+        attachments
+        and AITaskEntityFeature.SUPPORT_ATTACHMENTS not in entity.supported_features
+    ):
+        raise HomeAssistantError(
+            f"AI Task entity {entity_id} does not support attachments"
+        )
+
+    with async_get_chat_session(hass) as session:
+        resolved_attachments = await _resolve_attachments(hass, session, attachments)
+
+        task_result = await entity.internal_async_generate_image(
+            session,
+            GenImageTask(
+                name=task_name,
+                instructions=instructions,
+                attachments=resolved_attachments or None,
+            ),
+        )
+
+    service_result = task_result.as_dict()
+    image_data = service_result.pop("image_data")
+    if service_result.get("revised_prompt") is None:
+        service_result["revised_prompt"] = instructions
+
+    image_storage = hass.data[DATA_IMAGES]
+
+    if len(image_storage) + 1 > MAX_IMAGES:
+        _cleanup_images(image_storage, len(image_storage) + 1 - MAX_IMAGES)
+
+    current_time = datetime.now()
+    ext = mimetypes.guess_extension(task_result.mime_type, False) or ".png"
+    sanitized_task_name = RE_SANITIZE_FILENAME.sub("", slugify(task_name))
+    filename = f"{current_time.strftime('%Y-%m-%d_%H%M%S')}_{sanitized_task_name}{ext}"
+
+    image_storage[filename] = ImageData(
+        data=image_data,
+        timestamp=int(current_time.timestamp()),
+        mime_type=task_result.mime_type,
+        title=service_result["revised_prompt"],
+    )
+
+    def _purge_image(filename: str, now: datetime) -> None:
+        """Remove image from storage."""
+        image_storage.pop(filename, None)
+
+    if IMAGE_EXPIRY_TIME > 0:
+        async_call_later(hass, IMAGE_EXPIRY_TIME, partial(_purge_image, filename))
+
+    service_result["url"] = get_url(hass) + f"/api/{DOMAIN}/images/{filename}"
+    service_result["media_source_id"] = f"media-source://{DOMAIN}/images/{filename}"
+
+    return service_result
+
+
 @dataclass(slots=True)
 class GenDataTask:
     """Gen data task to be processed."""
@@ -167,3 +282,80 @@ class GenDataTaskResult:
             "conversation_id": self.conversation_id,
             "data": self.data,
         }
+
+
+@dataclass(slots=True)
+class GenImageTask:
+    """Gen image task to be processed."""
+
+    name: str
+    """Name of the task."""
+
+    instructions: str
+    """Instructions on what needs to be done."""
+
+    attachments: list[conversation.Attachment] | None = None
+    """List of attachments to go along the instructions."""
+
+    def __str__(self) -> str:
+        """Return task as a string."""
+        return f"<GenImageTask {self.name}: {id(self)}>"
+
+
+@dataclass(slots=True)
+class GenImageTaskResult:
+    """Result of gen image task."""
+
+    image_data: bytes
+    """Raw image data generated by the model."""
+
+    conversation_id: str
+    """Unique identifier for the conversation."""
+
+    mime_type: str
+    """MIME type of the generated image."""
+
+    width: int | None = None
+    """Width of the generated image, if available."""
+
+    height: int | None = None
+    """Height of the generated image, if available."""
+
+    model: str | None = None
+    """Model used to generate the image, if available."""
+
+    revised_prompt: str | None = None
+    """Revised prompt used to generate the image, if applicable."""
+
+    def as_dict(self) -> dict[str, Any]:
+        """Return result as a dict."""
+        return {
+            "image_data": self.image_data,
+            "conversation_id": self.conversation_id,
+            "mime_type": self.mime_type,
+            "width": self.width,
+            "height": self.height,
+            "model": self.model,
+            "revised_prompt": self.revised_prompt,
+        }
+
+
+@dataclass(slots=True)
+class ImageData:
+    """Image data for stored generated images."""
+
+    data: bytes
+    """Raw image data."""
+
+    timestamp: int
+    """Timestamp when the image was generated, as a Unix timestamp."""
+
+    mime_type: str
+    """MIME type of the image."""
+
+    title: str
+    """Title of the image, usually the prompt used to generate it."""
+
+    def __str__(self) -> str:
+        """Return image data as a string."""
+        return f"<ImageData {self.title}: {id(self)}>"

homeassistant/components/ai_task/translations/cs.json

@@ -1,14 +1,14 @@
 {
     "services": {
         "generate_data": {
-            "description": "Pou\u017e\u00edv\u00e1 AI ke spu\u0161t\u011bn\u00ed \u00falohy, kter\u00e1 generuje data.",
+            "description": "Pou\u017e\u00edv\u00e1 AI ke spu\u0161t\u011bn\u00ed \u00fakolu, kter\u00e1 generuje data.",
             "fields": {
                 "attachments": {
                     "description": "Seznam soubor\u016f, kter\u00e9 je t\u0159eba p\u0159ipojit k multimod\u00e1ln\u00ed anal\u00fdze AI.",
                     "name": "P\u0159\u00edlohy"
                 },
                 "entity_id": {
-                    "description": "ID entity, na kter\u00e9 se m\u00e1 \u00faloha spustit. Pokud nen\u00ed zad\u00e1no, bude pou\u017eita preferovan\u00e1 entita.",
+                    "description": "ID entity, na kter\u00e9 se m\u00e1 \u00fakol spustit. Pokud nen\u00ed zad\u00e1no, bude pou\u017eita preferovan\u00e1 entita.",
                     "name": "ID entity"
                 },
                 "instructions": {
@@ -16,7 +16,7 @@
                     "name": "Instrukce"
                 },
                 "structure": {
-                    "description": "Pokud je nastaveno, \u00faloha AI bude vypisovat pole s touto strukturou. Struktura je slovn\u00edk, kde kl\u00ed\u010de jsou n\u00e1zvy pol\u00ed a hodnoty obsahuj\u00ed \"description\", \"selector\" a nepovinn\u00e9 pole \"required\".",
+                    "description": "Pokud je nastaveno, \u00fakol AI bude vypisovat pole s touto strukturou. Struktura je slovn\u00edk, kde kl\u00ed\u010de jsou n\u00e1zvy pol\u00ed a hodnoty obsahuj\u00ed \"description\", \"selector\" a nepovinn\u00e9 pole \"required\".",
                     "name": "Strukturovan\u00fd v\u00fdstup"
                 },
                 "task_name": {
@@ -25,6 +25,28 @@
                 }
             },
             "name": "Vygenerovat data"
+        },
+        "generate_image": {
+            "description": "Pou\u017e\u00edv\u00e1 AI ke generov\u00e1n\u00ed obrazu.",
+            "fields": {
+                "attachments": {
+                    "description": "Seznam soubor\u016f, kter\u00e9 chcete p\u0159ipojit k pou\u017eit\u00ed jako reference.",
+                    "name": "P\u0159\u00edlohy"
+                },
+                "entity_id": {
+                    "description": "ID entity, na kter\u00e9 se m\u00e1 \u00fakol spustit.",
+                    "name": "ID entity"
+                },
+                "instructions": {
+                    "description": "Instrukce, kter\u00e9 vysv\u011btluj\u00ed obr\u00e1zek, kter\u00fd m\u00e1 b\u00fdt vygenerov\u00e1n.",
+                    "name": "Instrukce"
+                },
+                "task_name": {
+                    "description": "N\u00e1zev \u00fakolu.",
+                    "name": "N\u00e1zev \u00fakolu"
+                }
+            },
+            "name": "Vygenerovat obr\u00e1zek"
         }
     }
 }

homeassistant/components/ai_task/translations/de.json

@@ -25,6 +25,28 @@
                 }
             },
             "name": "Daten generieren"
+        },
+        "generate_image": {
+            "description": "Verwendet KI zur Bildgenerierung.",
+            "fields": {
+                "attachments": {
+                    "description": "Liste der Dateien, die als Referenzen angeh\u00e4ngt werden sollen.",
+                    "name": "Anh\u00e4nge"
+                },
+                "entity_id": {
+                    "description": "Entit\u00e4ts-ID, auf der der Task ausgef\u00fchrt werden soll.",
+                    "name": "Entit\u00e4ts-ID"
+                },
+                "instructions": {
+                    "description": "Anweisungen, die das zu erstellende Bild erkl\u00e4ren.",
+                    "name": "Anweisungen"
+                },
+                "task_name": {
+                    "description": "Name des Tasks.",
+                    "name": "Task-Name"
+                }
+            },
+            "name": "Bild generieren"
         }
     }
 }