mirror of
https://github.com/smkrv/ha-text-ai.git
synced 2026-07-21 22:54:00 +08:00
SMKRV
6e635f7e2f
Security: - H1 DNS rebinding TOCTOU: validate_endpoint returns (endpoint, resolved_ips); create_pinned_session builds an aiohttp session with a custom resolver that returns only the pre-validated IPs, closing the re-resolve gap. - H2/M3 Shared session cookie pollution: integration no longer uses HA shared clientsession; isolated session with DummyCookieJar prevents cross-integration cookie leaks. - Cloud metadata / link-local block added to allow_local_network mode to prevent IMDS exfiltration on cloud VMs. - L3 hard cap extended to history.async_get_history (not only service schema). ML/LLM correctness: - _is_openai_reasoning_model uses regex with gpt-5-chat* blacklist and handles OpenRouter-style openai/ prefix. Future o5/gpt-6 auto-recognized. - reasoning_effort=minimal for gpt-5 family, low for o-series. - Gemini 2.5 Pro gets thinking_budget=128 (Pro rejects 0, flash accepts 0). - Anthropic extracts first type=text block instead of hardcoded content[0]. - /no_think dedup uses word-boundary regex instead of substring. - DeepSeek-reasoner detected: skips /no_think; preserves reasoning_content. Reliability: - Exception chaining added to Gemini-block re-raises. - Top-level imports for json/re/hashlib (no more lazy stdlib imports). - allow_local_network logged at INFO, not WARNING on every setup. Code style: - PEP 604 type hints across all .py files (dict/list/| None). No breaking changes for users. Internal API: validate_endpoint return type changed from str to tuple[str, list[str]].
399 lines
15 KiB
Python
399 lines
15 KiB
Python
"""
|
|
The HA Text AI integration.
|
|
|
|
@license: MIT (https://opensource.org/licenses/MIT)
|
|
@author: SMKRV
|
|
@github: https://github.com/smkrv/ha-text-ai
|
|
@source: https://github.com/smkrv/ha-text-ai
|
|
"""
|
|
from __future__ import annotations
|
|
|
|
import logging
|
|
from typing import Any
|
|
|
|
import asyncio
|
|
|
|
import voluptuous as vol
|
|
|
|
from homeassistant.config_entries import ConfigEntry
|
|
from homeassistant.const import CONF_API_KEY, CONF_NAME
|
|
from homeassistant.core import HomeAssistant, ServiceCall, SupportsResponse
|
|
from homeassistant.exceptions import ConfigEntryNotReady, HomeAssistantError
|
|
from homeassistant.helpers import config_validation as cv
|
|
from homeassistant.util import dt as dt_util
|
|
|
|
from .coordinator import HATextAICoordinator
|
|
from .api_client import APIClient
|
|
from .utils import create_pinned_session, normalize_name, safe_log_data, validate_endpoint
|
|
from .providers import get_default_endpoint, get_default_model, build_auth_headers
|
|
from .const import (
|
|
DOMAIN,
|
|
PLATFORMS,
|
|
CONF_MODEL,
|
|
CONF_TEMPERATURE,
|
|
CONF_MAX_TOKENS,
|
|
CONF_API_ENDPOINT,
|
|
CONF_REQUEST_INTERVAL,
|
|
CONF_API_TIMEOUT,
|
|
CONF_API_PROVIDER,
|
|
CONF_CONTEXT_MESSAGES,
|
|
DEFAULT_TEMPERATURE,
|
|
DEFAULT_MAX_TOKENS,
|
|
DEFAULT_REQUEST_INTERVAL,
|
|
DEFAULT_API_TIMEOUT,
|
|
DEFAULT_CONTEXT_MESSAGES,
|
|
SERVICE_ASK_QUESTION,
|
|
SERVICE_CLEAR_HISTORY,
|
|
SERVICE_GET_HISTORY,
|
|
SERVICE_SET_SYSTEM_PROMPT,
|
|
DEFAULT_MAX_HISTORY,
|
|
CONF_MAX_HISTORY_SIZE,
|
|
CONF_ALLOW_LOCAL_NETWORK,
|
|
DEFAULT_ALLOW_LOCAL_NETWORK,
|
|
CONF_DISABLE_THINKING,
|
|
DEFAULT_DISABLE_THINKING,
|
|
)
|
|
|
|
_LOGGER = logging.getLogger(__name__)
|
|
|
|
CONFIG_SCHEMA = cv.config_entry_only_config_schema(DOMAIN)
|
|
|
|
SERVICE_SCHEMA_ASK_QUESTION = vol.Schema({
|
|
vol.Required("instance"): cv.string,
|
|
vol.Required("question"): vol.All(cv.string, vol.Length(min=1, max=100000)),
|
|
vol.Optional("system_prompt"): vol.All(cv.string, vol.Length(max=50000)),
|
|
vol.Optional("model"): cv.string,
|
|
vol.Optional("temperature"): vol.All(
|
|
vol.Coerce(float), vol.Range(min=0.0, max=2.0)
|
|
),
|
|
vol.Optional("max_tokens"): cv.positive_int,
|
|
vol.Optional("context_messages"): cv.positive_int,
|
|
vol.Optional("structured_output", default=False): cv.boolean,
|
|
vol.Optional("json_schema"): vol.All(cv.string, vol.Length(max=50000)),
|
|
vol.Optional("disable_thinking"): cv.boolean,
|
|
})
|
|
|
|
SERVICE_SCHEMA_SET_SYSTEM_PROMPT = vol.Schema({
|
|
vol.Required("instance"): cv.string,
|
|
vol.Required("prompt"): cv.string,
|
|
})
|
|
|
|
SERVICE_SCHEMA_GET_HISTORY = vol.Schema({
|
|
vol.Required("instance"): cv.string,
|
|
# Cap limit to protect automations from huge response payloads.
|
|
vol.Optional("limit", default=10): vol.All(cv.positive_int, vol.Range(min=1, max=100)),
|
|
vol.Optional("filter_model"): cv.string,
|
|
vol.Optional("start_date"): cv.string,
|
|
vol.Optional("include_metadata"): cv.boolean,
|
|
vol.Optional("sort_order"): vol.In(["newest", "oldest"]),
|
|
})
|
|
|
|
def get_coordinator_by_instance(hass: HomeAssistant, instance: str) -> HATextAICoordinator:
|
|
"""Get coordinator by instance name or normalized name.
|
|
|
|
Accepts instance_name, normalized_name, or sensor entity_id.
|
|
"""
|
|
if instance.startswith("sensor."):
|
|
instance = instance.replace("sensor.ha_text_ai_", "", 1)
|
|
|
|
normalized_input = normalize_name(instance)
|
|
|
|
for entry_id, coord in hass.data[DOMAIN].items():
|
|
if not isinstance(coord, HATextAICoordinator):
|
|
continue
|
|
if (
|
|
coord.instance_name.lower() == instance.lower()
|
|
or coord.normalized_name == normalized_input
|
|
):
|
|
return coord
|
|
|
|
raise HomeAssistantError(f"Instance {instance} not found")
|
|
|
|
async def async_setup(hass: HomeAssistant, config: dict[str, Any]) -> bool:
|
|
"""Set up the Home Assistant Text AI component."""
|
|
# Initialize domain data storage
|
|
hass.data.setdefault(DOMAIN, {})
|
|
|
|
async def async_ask_question(call: ServiceCall) -> dict:
|
|
"""Handle ask_question service with response data."""
|
|
try:
|
|
coordinator = get_coordinator_by_instance(hass, call.data["instance"])
|
|
response = await coordinator.async_ask_question(
|
|
question=call.data["question"],
|
|
model=call.data.get("model"),
|
|
temperature=call.data.get("temperature"),
|
|
max_tokens=call.data.get("max_tokens"),
|
|
system_prompt=call.data.get("system_prompt"),
|
|
context_messages=call.data.get("context_messages"),
|
|
structured_output=call.data.get("structured_output", False),
|
|
json_schema=call.data.get("json_schema"),
|
|
disable_thinking=call.data.get("disable_thinking"),
|
|
)
|
|
|
|
# Return structured response data
|
|
return {
|
|
"response_text": response.get("content", ""),
|
|
"tokens_used": response.get("tokens", {}).get("total", 0),
|
|
"prompt_tokens": response.get("tokens", {}).get("prompt", 0),
|
|
"completion_tokens": response.get("tokens", {}).get("completion", 0),
|
|
"model_used": response.get("model", call.data.get("model", coordinator.model)),
|
|
"instance": call.data["instance"],
|
|
"question": call.data["question"],
|
|
"timestamp": response.get("timestamp"),
|
|
"success": True
|
|
}
|
|
except Exception as err:
|
|
_LOGGER.error("Error asking question: %s", str(err))
|
|
# Return error response
|
|
return {
|
|
"response_text": "",
|
|
"tokens_used": 0,
|
|
"prompt_tokens": 0,
|
|
"completion_tokens": 0,
|
|
"model_used": call.data.get("model", ""),
|
|
"instance": call.data["instance"],
|
|
"question": call.data["question"],
|
|
"timestamp": dt_util.utcnow().isoformat(),
|
|
"success": False,
|
|
"error": str(err),
|
|
"error_type": type(err).__name__
|
|
}
|
|
|
|
async def async_clear_history(call: ServiceCall) -> None:
|
|
"""Handle clear_history service."""
|
|
try:
|
|
coordinator = get_coordinator_by_instance(hass, call.data["instance"])
|
|
await coordinator.async_clear_history()
|
|
except Exception as err:
|
|
_LOGGER.error("Error clearing history: %s", str(err))
|
|
raise HomeAssistantError(f"Failed to clear history: {str(err)}") from err
|
|
|
|
async def async_get_history(call: ServiceCall) -> list:
|
|
"""Handle get_history service."""
|
|
try:
|
|
coordinator = get_coordinator_by_instance(hass, call.data["instance"])
|
|
return await coordinator.async_get_history(
|
|
limit=call.data.get("limit"),
|
|
filter_model=call.data.get("filter_model"),
|
|
start_date=call.data.get("start_date"),
|
|
include_metadata=call.data.get("include_metadata", False),
|
|
sort_order=call.data.get("sort_order", "newest")
|
|
)
|
|
except Exception as err:
|
|
_LOGGER.error("Error getting history: %s", str(err))
|
|
raise HomeAssistantError(f"Failed to get history: {str(err)}") from err
|
|
|
|
async def async_set_system_prompt(call: ServiceCall) -> None:
|
|
"""Handle set_system_prompt service."""
|
|
try:
|
|
coordinator = get_coordinator_by_instance(hass, call.data["instance"])
|
|
await coordinator.async_set_system_prompt(call.data["prompt"])
|
|
except Exception as err:
|
|
_LOGGER.error("Error setting system prompt: %s", str(err))
|
|
raise HomeAssistantError(f"Failed to set system prompt: {str(err)}") from err
|
|
|
|
# Register services
|
|
hass.services.async_register(
|
|
DOMAIN,
|
|
SERVICE_ASK_QUESTION,
|
|
async_ask_question,
|
|
schema=SERVICE_SCHEMA_ASK_QUESTION,
|
|
supports_response=SupportsResponse.OPTIONAL
|
|
)
|
|
|
|
hass.services.async_register(
|
|
DOMAIN,
|
|
SERVICE_CLEAR_HISTORY,
|
|
async_clear_history,
|
|
schema=vol.Schema({vol.Required("instance"): cv.string})
|
|
)
|
|
|
|
hass.services.async_register(
|
|
DOMAIN,
|
|
SERVICE_GET_HISTORY,
|
|
async_get_history,
|
|
schema=SERVICE_SCHEMA_GET_HISTORY,
|
|
supports_response=SupportsResponse.OPTIONAL
|
|
)
|
|
|
|
hass.services.async_register(
|
|
DOMAIN,
|
|
SERVICE_SET_SYSTEM_PROMPT,
|
|
async_set_system_prompt,
|
|
schema=SERVICE_SCHEMA_SET_SYSTEM_PROMPT
|
|
)
|
|
|
|
return True
|
|
|
|
async def async_check_api(session, endpoint: str, headers: dict, provider: str, api_timeout: int = DEFAULT_API_TIMEOUT) -> bool:
|
|
"""Check API availability using provider registry configuration."""
|
|
try:
|
|
from .providers import get_provider_config
|
|
provider_config = get_provider_config(provider)
|
|
check_path = provider_config.get("check_path")
|
|
|
|
if check_path is None:
|
|
# Provider does not support /models check (e.g. Gemini)
|
|
auth_header = provider_config["auth_header"]
|
|
auth_value = headers.get(auth_header, "").replace(provider_config.get("auth_prefix", ""), "")
|
|
if auth_value:
|
|
return True
|
|
_LOGGER.error("API key is missing or empty for %s", provider)
|
|
return False
|
|
|
|
check_url = f"{endpoint}{check_path}"
|
|
|
|
async with asyncio.timeout(api_timeout):
|
|
async with session.get(check_url, headers=headers) as response:
|
|
if response.status == 200:
|
|
return True
|
|
elif response.status == 401:
|
|
_LOGGER.error("Invalid API key")
|
|
return False
|
|
elif response.status == 429:
|
|
_LOGGER.warning("Rate limit exceeded during API check")
|
|
return False
|
|
else:
|
|
_LOGGER.error("API check failed with status: %d", response.status)
|
|
return False
|
|
except Exception as ex:
|
|
_LOGGER.error("API check error: %s", str(ex))
|
|
return False
|
|
|
|
async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
|
|
"""Set up HA Text AI from a config entry."""
|
|
_LOGGER.debug("Setting up HA Text AI entry: %s", safe_log_data(dict(entry.data)))
|
|
|
|
try:
|
|
# Get provider from data or options (options takes precedence)
|
|
config = {**entry.data, **entry.options}
|
|
api_provider = config.get(CONF_API_PROVIDER)
|
|
|
|
if not api_provider:
|
|
_LOGGER.error("API provider not specified")
|
|
raise ConfigEntryNotReady("API provider is required")
|
|
|
|
model = config.get(CONF_MODEL, get_default_model(api_provider))
|
|
raw_endpoint = config.get(CONF_API_ENDPOINT, get_default_endpoint(api_provider))
|
|
allow_local = config.get(CONF_ALLOW_LOCAL_NETWORK, DEFAULT_ALLOW_LOCAL_NETWORK)
|
|
if allow_local:
|
|
_LOGGER.info(
|
|
"Local network mode enabled for endpoint %s — "
|
|
"SSRF protection relaxed for self-hosted proxies",
|
|
raw_endpoint,
|
|
)
|
|
try:
|
|
endpoint, resolved_ips = await validate_endpoint(
|
|
hass, raw_endpoint, allow_local=allow_local
|
|
)
|
|
except ValueError as err:
|
|
_LOGGER.error("Invalid API endpoint: %s", err)
|
|
raise ConfigEntryNotReady(f"Invalid API endpoint: {err}") from err
|
|
|
|
# Pinned session closes DNS-rebinding TOCTOU and isolates cookies
|
|
# from other integrations sharing the same endpoint hostname.
|
|
session = create_pinned_session(hass, endpoint, resolved_ips)
|
|
# API key can now be updated via options
|
|
api_key = config.get(CONF_API_KEY, entry.data.get(CONF_API_KEY))
|
|
instance_name = entry.data.get(CONF_NAME, entry.entry_id)
|
|
request_interval = config.get(CONF_REQUEST_INTERVAL, DEFAULT_REQUEST_INTERVAL)
|
|
api_timeout = config.get(CONF_API_TIMEOUT, DEFAULT_API_TIMEOUT)
|
|
max_tokens = config.get(CONF_MAX_TOKENS, DEFAULT_MAX_TOKENS)
|
|
temperature = config.get(CONF_TEMPERATURE, DEFAULT_TEMPERATURE)
|
|
max_history_size = config.get(CONF_MAX_HISTORY_SIZE, DEFAULT_MAX_HISTORY)
|
|
context_messages = config.get(CONF_CONTEXT_MESSAGES, DEFAULT_CONTEXT_MESSAGES)
|
|
disable_thinking = config.get(CONF_DISABLE_THINKING, DEFAULT_DISABLE_THINKING)
|
|
|
|
headers = build_auth_headers(api_provider, api_key)
|
|
|
|
if not await async_check_api(session, endpoint, headers, api_provider, api_timeout):
|
|
raise ConfigEntryNotReady("API connection failed")
|
|
|
|
_LOGGER.debug("Creating API client for %s with endpoint %s", api_provider, endpoint)
|
|
|
|
api_client = APIClient(
|
|
session=session,
|
|
endpoint=endpoint,
|
|
headers=headers,
|
|
api_provider=api_provider,
|
|
model=model,
|
|
api_timeout=api_timeout,
|
|
api_key=api_key,
|
|
)
|
|
|
|
coordinator = HATextAICoordinator(
|
|
hass=hass,
|
|
client=api_client,
|
|
model=model,
|
|
update_interval=request_interval,
|
|
instance_name=instance_name,
|
|
config_entry=entry,
|
|
max_tokens=max_tokens,
|
|
temperature=temperature,
|
|
max_history_size=max_history_size,
|
|
context_messages=context_messages,
|
|
api_timeout=api_timeout,
|
|
disable_thinking=disable_thinking,
|
|
)
|
|
|
|
# Initialize coordinator (directories, history, metrics)
|
|
await coordinator.async_initialize()
|
|
|
|
_LOGGER.debug("Created coordinator for %s", instance_name)
|
|
|
|
# Store coordinator
|
|
hass.data.setdefault(DOMAIN, {})
|
|
hass.data[DOMAIN][entry.entry_id] = coordinator
|
|
|
|
_LOGGER.debug("Stored coordinator in hass.data[%s][%s]", DOMAIN, entry.entry_id)
|
|
|
|
# Set up platforms
|
|
await hass.config_entries.async_forward_entry_setups(entry, PLATFORMS)
|
|
|
|
# Register update listener for options changes
|
|
entry.async_on_unload(entry.add_update_listener(async_update_options))
|
|
|
|
_LOGGER.debug("Setup completed for %s", instance_name)
|
|
|
|
return True
|
|
|
|
except Exception as err:
|
|
_LOGGER.exception("Error setting up HA Text AI: %s", err)
|
|
raise
|
|
|
|
async def async_update_options(hass: HomeAssistant, entry: ConfigEntry) -> None:
|
|
"""Handle options update - reload the config entry."""
|
|
_LOGGER.info("Options updated for %s, reloading integration", entry.title)
|
|
await hass.config_entries.async_reload(entry.entry_id)
|
|
|
|
async def async_unload_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
|
|
"""Unload a config entry."""
|
|
try:
|
|
unload_ok = await hass.config_entries.async_unload_platforms(entry, PLATFORMS)
|
|
if unload_ok and entry.entry_id in hass.data[DOMAIN]:
|
|
coordinator = hass.data[DOMAIN].pop(entry.entry_id)
|
|
|
|
if hasattr(coordinator.client, 'shutdown'):
|
|
await coordinator.client.shutdown()
|
|
|
|
await coordinator.async_shutdown()
|
|
|
|
# When removing the last config entry, also unregister services and
|
|
# clear the domain bucket so HA doesn't show stale services in the UI.
|
|
if not hass.data.get(DOMAIN):
|
|
hass.data.pop(DOMAIN, None)
|
|
for service in (
|
|
SERVICE_ASK_QUESTION,
|
|
SERVICE_CLEAR_HISTORY,
|
|
SERVICE_GET_HISTORY,
|
|
SERVICE_SET_SYSTEM_PROMPT,
|
|
):
|
|
if hass.services.has_service(DOMAIN, service):
|
|
hass.services.async_remove(DOMAIN, service)
|
|
|
|
return unload_ok
|
|
|
|
except Exception as ex:
|
|
_LOGGER.exception("Error unloading entry: %s", str(ex))
|
|
return False
|