Parse description in structured mode using user-specified field.

Author: valentinfrlch

custom_components/llmvision/__init__.py

@@ -73,6 +73,7 @@
     RESPONSE_FORMAT,
     STRUCTURE,
     TITLE_FIELD,
+    DESCPRIPTION_FIELD,
 )
 
 CONFIG_SCHEMA = cv.config_entry_only_config_schema(DOMAIN)
@@ -472,6 +473,7 @@ def __init__(self, data_call):
         self.response_format = data_call.data.get(RESPONSE_FORMAT, "text")
         self.structure = data_call.data.get(STRUCTURE, None)
         self.title_field = data_call.data.get(TITLE_FIELD, "")
+        self.description_field = data_call.data.get(DESCPRIPTION_FIELD, "")
         self.memory: Memory | None = None
 
         # ------------ Create Event ------------
@@ -555,11 +557,24 @@ async def _create_event(
         title = response.get("title") or "Motion detected"
         title = str(title)
 
+        description = response.get("response_text", "")
+        structured_response = response.get("structured_response")
+
+        # Handle structured response for description extraction
+        if (
+            call.response_format == "json"
+            and call.description_field
+            and isinstance(structured_response, dict)
+        ):
+            description_field_value = structured_response.get(call.description_field)
+            if description_field_value is not None:
+                description = str(description_field_value)
+
         await timeline.create_event(
             start=start,
             end=dt_util.now() + timedelta(minutes=1),
             title=title,
-            description=response["response_text"],
+            description=description,
             key_frame=key_frame,
             camera_name=camera_name,
             label="",

custom_components/llmvision/const.py

@@ -67,6 +67,7 @@
 RESPONSE_FORMAT = "response_format"
 STRUCTURE = "structure"
 TITLE_FIELD = "title_field"
+DESCPRIPTION_FIELD = "description_field"
 INCLUDE_FILENAME = "include_filename"
 EXPOSE_IMAGES = "expose_images"
 GENERATE_TITLE = "generate_title"

custom_components/llmvision/providers.py

@@ -265,8 +265,9 @@ async def call(self, call: Any, _is_fallback_retry: bool = False):
                 # If parsing fails, return as text
                 result["response_text"] = response_text
             else:
-                # Also keep text version for backward compatibility
-                result["response_text"] = response_text
+                # drop response_text if structured_response is present
+                if "structured_response" in result:
+                    del result["response_text"]
         else:
             result["response_text"] = response_text
 

custom_components/llmvision/services.yaml

@@ -112,18 +112,26 @@ image_analyzer:
             - "json"
     structure:
       name: Structure
-      description: 'JSON schema defining the expected response structure (only used when response_format is json). To enable automatic title generation for calendar events, include a field in your schema for the title (e.g., "title": {"type": "string", "description": "Event title"}) and specify the field name below.'
+      description: 'JSON schema defining the expected response structure (only used when response_format is json). To enable automatic title generation for timeline events, include a field in your schema for the title (e.g., "title": {"type": "string", "description": "Event title"}) and specify the field names below.'
       required: false
-      example: '{"type": "object", "properties": {"package_detected": {"type": "boolean", "description": "Is a package visible"}, "confidence": {"type": "number", "minimum": 0, "maximum": 100}}, "required": ["package_detected"]}'
+      example: '{"type": "object", "properties": {"title": {"type": "string", "description": "Event title"}, "description": {"type": "string", "description": "Event description"}, "confidence": {"type": "number", "minimum": 0, "maximum": 100}}, "required": ["title", "description", "confidence"], "additionalProperties": false}'
       selector:
         text:
           multiline: true
     title_field:
       name: Title Field Name
-      description: 'Name of the field in your JSON schema that contains the event title (used for calendar entries and notifications). Leave empty to use fallback title "Motion detected".'
+      description: 'Name of the field in your JSON schema that contains the event title (used for timeline). Leave empty to use fallback title "Motion detected".'
       required: false
       example: 'title'
-      default: ''
+      default: 'title'
+      selector:
+        text:
+    description_field:
+      name: Description Field Name
+      description: 'Name of the field in your JSON schema that contains the event description (used for timeline).'
+      required: false
+      example: 'description'
+      default: 'description'
       selector:
         text:
 
@@ -251,18 +259,26 @@ video_analyzer:
             - "json"
     structure:
       name: Structure
-      description: 'JSON schema defining the expected response structure (only used when response_format is json). To enable automatic title generation for calendar events, include a field in your schema for the title (e.g., "title": {"type": "string", "description": "Event title"}) and specify the field name below.'
+      description: 'JSON schema defining the expected response structure (only used when response_format is json). To enable automatic title generation for timeline events, include a field in your schema for the title (e.g., "title": {"type": "string", "description": "Event title"}) and specify the field names below.'
       required: false
-      example: '{"type": "object", "properties": {"package_detected": {"type": "boolean", "description": "Is a package visible"}, "confidence": {"type": "number", "minimum": 0, "maximum": 100}}, "required": ["package_detected"]}'
+      example: '{"type": "object", "properties": {"title": {"type": "string", "description": "Event title"}, "description": {"type": "string", "description": "Event description"}, "confidence": {"type": "number", "minimum": 0, "maximum": 100}}, "required": ["title", "description", "confidence"], "additionalProperties": false}'
       selector:
         text:
           multiline: true
     title_field:
       name: Title Field Name
-      description: 'Name of the field in your JSON schema that contains the event title (used for calendar entries and notifications). Leave empty to use fallback title "Motion detected".'
+      description: 'Name of the field in your JSON schema that contains the event title (used for timeline). Leave empty to use fallback title "Motion detected".'
       required: false
       example: 'title'
-      default: ''
+      default: 'title'
+      selector:
+        text:
+    description_field:
+      name: Description Field Name
+      description: 'Name of the field in your JSON schema that contains the event description (used for timeline).'
+      required: false
+      example: 'description'
+      default: 'description'
       selector:
         text:
 
@@ -393,18 +409,26 @@ stream_analyzer:
             - "json"
     structure:
       name: Structure
-      description: 'JSON schema defining the expected response structure (only used when response_format is json). To enable automatic title generation for calendar events, include a field in your schema for the title (e.g., "title": {"type": "string", "description": "Event title"}) and specify the field name below.'
+      description: 'JSON schema defining the expected response structure (only used when response_format is json). To enable automatic title generation for timeline events, include a field in your schema for the title (e.g., "title": {"type": "string", "description": "Event title"}) and specify the field names below.'
       required: false
-      example: '{"type": "object", "properties": {"package_detected": {"type": "boolean", "description": "Is a package visible"}, "confidence": {"type": "number", "minimum": 0, "maximum": 100}}, "required": ["package_detected"]}'
+      example: '{"type": "object", "properties": {"title": {"type": "string", "description": "Event title"}, "description": {"type": "string", "description": "Event description"}, "confidence": {"type": "number", "minimum": 0, "maximum": 100}}, "required": ["title", "description", "confidence"], "additionalProperties": false}'
       selector:
         text:
           multiline: true
     title_field:
       name: Title Field Name
-      description: 'Name of the field in your JSON schema that contains the event title (used for calendar entries and notifications). Leave empty to use fallback title "Motion detected".'
+      description: 'Name of the field in your JSON schema that contains the event title (used for timeline). Leave empty to use fallback title "Motion detected".'
       required: false
       example: 'title'
-      default: ''
+      default: 'title'
+      selector:
+        text:
+    description_field:
+      name: Description Field Name
+      description: 'Name of the field in your JSON schema that contains the event description (used for timeline).'
+      required: false
+      example: 'description'
+      default: 'description'
       selector:
         text: