ha-text-ai/custom_components/ha_text_ai/__init__.py

"""
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, EVENT_HOMEASSISTANT_CLOSE
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,
    # No default and no schema max: omitting limit returns the full history
    # (pre-2.5.0 behavior) and oversized values are clamped to
    # ABSOLUTE_MAX_HISTORY_SIZE in history.async_get_history instead of
    # failing the whole service call.
    vol.Optional("limit"): vol.All(cv.positive_int, vol.Range(min=1)),
    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_register_services(hass)
    return True

def _async_register_services(hass: HomeAssistant) -> None:
    """Register domain services; safe to call again after unload.

    Unloading the last config entry unregisters the services, and a config
    entry reload (every options change does one) runs unload + setup_entry
    without re-running async_setup — so setup_entry must be able to bring
    the services back.
    """
    if hass.services.has_service(DOMAIN, SERVICE_ASK_QUESTION):
        return

    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) -> dict:
        """Handle get_history service."""
        try:
            coordinator = get_coordinator_by_instance(hass, call.data["instance"])
            history = 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")
            )
            # HA requires action responses to be dicts. The bare list made
            # every return_response call fail with a server error, so this
            # path never worked before and the wrapper breaks no consumer.
            return {"history": history}
        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
    )

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, allow_redirects=False
            ) 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)))

    session = None
    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.
        # The integration owns this session: APIClient.shutdown() closes it
        # on unload, the except handler below closes it on failed setup.
        session = create_pinned_session(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

        # A reload after the last entry was unloaded needs the services back.
        _async_register_services(hass)

        _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))

        # HA Core stop does not unload entries, so close the dedicated
        # session on the CLOSE event too; unload removes this listener
        # and closes the session via APIClient.shutdown() instead.
        async def _async_close_session_on_stop(_event) -> None:
            if not session.closed:
                await session.close()

        entry.async_on_unload(
            hass.bus.async_listen_once(
                EVENT_HOMEASSISTANT_CLOSE, _async_close_session_on_stop
            )
        )

        _LOGGER.debug("Setup completed for %s", instance_name)

        return True

    except Exception as err:
        _LOGGER.exception("Error setting up HA Text AI: %s", err)
        if session is not None and not session.closed:
            await session.close()
        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