|
| 1 | +"""LLM API for Frigate integration.""" |
| 2 | + |
| 3 | +from __future__ import annotations |
| 4 | + |
| 5 | +import logging |
| 6 | +from typing import Any |
| 7 | + |
| 8 | +import voluptuous as vol |
| 9 | + |
| 10 | +from homeassistant.core import HomeAssistant |
| 11 | +from homeassistant.helpers import config_validation as cv, llm |
| 12 | +from homeassistant.util.json import JsonObjectType |
| 13 | + |
| 14 | +from .api import FrigateApiClientError |
| 15 | +from .const import ATTR_CLIENT, ATTR_CONFIG, DOMAIN |
| 16 | + |
| 17 | +_LOGGER = logging.getLogger(__name__) |
| 18 | + |
| 19 | +FRIGATE_SERVICES_API_ID = "frigate_services" |
| 20 | + |
| 21 | + |
| 22 | +class FrigateQueryTool(llm.Tool): |
| 23 | + """Tool that queries the Frigate NVR chat API.""" |
| 24 | + |
| 25 | + name = "frigate_query" |
| 26 | + description = ( |
| 27 | + "Ask Frigate NVR a question about your security cameras, recent events, " |
| 28 | + "detected objects, or what is currently visible on a camera. Use this tool " |
| 29 | + "when the user asks about their security cameras, surveillance footage, " |
| 30 | + "who or what was detected, or wants to know what a camera sees right now. " |
| 31 | + "You can optionally specify a camera name to include a live image from " |
| 32 | + "that camera for visual analysis." |
| 33 | + ) |
| 34 | + |
| 35 | + def __init__(self, camera_names: list[str]) -> None: |
| 36 | + """Initialize the tool with available camera names.""" |
| 37 | + schema: dict[vol.Marker, Any] = { |
| 38 | + vol.Required( |
| 39 | + "query", |
| 40 | + description="The user's question about their security cameras or surveillance system", |
| 41 | + ): cv.string, |
| 42 | + } |
| 43 | + if camera_names: |
| 44 | + schema[ |
| 45 | + vol.Optional( |
| 46 | + "camera_name", |
| 47 | + description=( |
| 48 | + "The name of a specific camera to include a live image " |
| 49 | + "from for visual context. Use when the user asks about " |
| 50 | + "what a specific camera sees right now." |
| 51 | + ), |
| 52 | + ) |
| 53 | + ] = vol.In(camera_names) |
| 54 | + self.parameters = vol.Schema(schema) |
| 55 | + |
| 56 | + async def async_call( |
| 57 | + self, |
| 58 | + hass: HomeAssistant, |
| 59 | + tool_input: llm.ToolInput, |
| 60 | + llm_context: llm.LLMContext, |
| 61 | + ) -> JsonObjectType: |
| 62 | + """Call the Frigate chat completion API.""" |
| 63 | + query = tool_input.tool_args["query"] |
| 64 | + camera_name = tool_input.tool_args.get("camera_name") |
| 65 | + |
| 66 | + # Find the right client |
| 67 | + client = None |
| 68 | + for entry_id, entry_data in hass.data[DOMAIN].items(): |
| 69 | + if not isinstance(entry_data, dict) or ATTR_CLIENT not in entry_data: |
| 70 | + continue |
| 71 | + if camera_name: |
| 72 | + config = entry_data.get(ATTR_CONFIG, {}) |
| 73 | + if camera_name in config.get("cameras", {}): |
| 74 | + client = entry_data[ATTR_CLIENT] |
| 75 | + break |
| 76 | + else: |
| 77 | + client = entry_data[ATTR_CLIENT] |
| 78 | + break |
| 79 | + |
| 80 | + if client is None: |
| 81 | + return {"error": "No Frigate instance available"} |
| 82 | + |
| 83 | + try: |
| 84 | + result = await client.async_chat_completion(query, camera_name) |
| 85 | + content = result.get("message", {}).get("content", "") |
| 86 | + return {"response": content} |
| 87 | + except FrigateApiClientError as exc: |
| 88 | + _LOGGER.error("Frigate query failed: %s", exc) |
| 89 | + return {"error": f"Frigate query failed: {exc}"} |
| 90 | + |
| 91 | + |
| 92 | +class FrigateServiceAPI(llm.API): |
| 93 | + """LLM API exposing Frigate Services.""" |
| 94 | + |
| 95 | + def __init__(self, hass: HomeAssistant) -> None: |
| 96 | + """Initialize the API.""" |
| 97 | + super().__init__( |
| 98 | + hass=hass, |
| 99 | + id=FRIGATE_SERVICES_API_ID, |
| 100 | + name="Frigate Services", |
| 101 | + ) |
| 102 | + |
| 103 | + async def async_get_api_instance( |
| 104 | + self, llm_context: llm.LLMContext |
| 105 | + ) -> llm.APIInstance: |
| 106 | + """Return the instance of the API.""" |
| 107 | + # Collect camera names from all Frigate config entries |
| 108 | + camera_names: list[str] = [] |
| 109 | + for entry_id, entry_data in self.hass.data.get(DOMAIN, {}).items(): |
| 110 | + if not isinstance(entry_data, dict) or ATTR_CONFIG not in entry_data: |
| 111 | + continue |
| 112 | + config = entry_data[ATTR_CONFIG] |
| 113 | + for cam_name in config.get("cameras", {}).keys(): |
| 114 | + if cam_name not in camera_names: |
| 115 | + camera_names.append(cam_name) |
| 116 | + |
| 117 | + camera_list = ", ".join(camera_names) if camera_names else "none detected" |
| 118 | + api_prompt = ( |
| 119 | + "Use Frigate Services to ask questions about security cameras, " |
| 120 | + "detected events, and live camera feeds. Frigate is an NVR " |
| 121 | + "(Network Video Recorder) that monitors security cameras, detects " |
| 122 | + "objects like people, cars, and animals, and records events. " |
| 123 | + f"Available cameras: {camera_list}." |
| 124 | + ) |
| 125 | + |
| 126 | + tool = FrigateQueryTool(camera_names) |
| 127 | + |
| 128 | + return llm.APIInstance( |
| 129 | + api=self, |
| 130 | + api_prompt=api_prompt, |
| 131 | + llm_context=llm_context, |
| 132 | + tools=[tool], |
| 133 | + ) |
0 commit comments