Release v1.0.1c

.github/workflows/hassfest.yaml

@@ -2,13 +2,44 @@ name: Validate with hassfest
 
 on:
   push:
+    branches:
+      - main
+      - dev
+    paths:
+      - 'custom_components/**'
+      - '.github/workflows/**'
   pull_request:
+    branches:
+      - main
+    paths:
+      - 'custom_components/**'
+      - '.github/workflows/**'
   schedule:
-    - cron: "0 0 * * *"
+    - cron: "0 0 * * *"  # Run daily at midnight UTC
+  workflow_dispatch:  # Allow manual trigger
 
 jobs:
   validate:
+    name: Validate with hassfest
     runs-on: ubuntu-latest
+    timeout-minutes: 10
+
     steps:
-      - uses: actions/checkout@v3
+      - name: ⤵️ Check out code from GitHub
-      - uses: home-assistant/actions/hassfest@master
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: 🚀 Run hassfest validation
+        uses: home-assistant/actions/hassfest@master
+        with:
+          strict: true
+
+      - name: ℹ️ Print hassfest version
+        if: always()
+        run: |
+          echo "Hassfest version: $(hassfest --version)"
+
+    concurrency:
+      group: ${{ github.workflow }}-${{ github.ref }}
+      cancel-in-progress: true

.github/workflows/validate.yaml

@@ -1,24 +0,0 @@
-name: Validate
-
-on:
-  push:
-  pull_request:
-  schedule:
-    - cron: "0 0 * * *"
-
-jobs:
-  validate:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v3
-      - name: Set up Python
-        uses: actions/setup-python@v4
-        with:
-          python-version: "3.x"
-      - name: Install dependencies
-        run: |
-          python -m pip install --upgrade pip
-          pip install -r requirements.txt
-      - name: Run tests
-        run: |
-          pytest

README.md

@@ -1,145 +1,165 @@
-# 🤖 HA text AI Integration for Home Assistant
+# 🤖 HA Text AI for Home Assistant
 
 <div align="center">
 
-![GitHub release](https://img.shields.io/github/release/smkrv/ha-text-ai.svg)
+![GitHub release](https://img.shields.io/github/release/smkrv/ha-text-ai.svg?style=flat-square)
+![GitHub downloads](https://img.shields.io/github/downloads/smkrv/ha-text-ai/total.svg?style=flat-square)
 ![GitHub stars](https://img.shields.io/github/stars/smkrv/ha-text-ai.svg?style=social)
-![GitHub forks](https://img.shields.io/github/forks/smkrv/ha-text-ai.svg?style=social)
+![GitHub last commit](https://img.shields.io/github/last-commit/smkrv/ha-text-ai.svg?style=flat-square)
-![GitHub issues](https://img.shields.io/github/issues/smkrv/ha-text-ai.svg)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
-[![hacs_badge](https://img.shields.io/badge/HACS-Default-orange.svg)](https://github.com/hacs/integration)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 </div>
 
 <p align="center">
-Powerful OpenAI integration for Home Assistant enabling natural language interaction with your smart home
+Transform your smart home experience with powerful AI assistance powered by OpenAI's GPT models
 </p>
 
 ---
 
-## 📋 Table of Contents
+## 🌟 Features
-- [Features](#-features)
-- [Installation](#-installation)
-- [Configuration](#-configuration)
-- [Services](#-services)
-- [Advanced Usage](#-advanced-usage)
-- [Troubleshooting](#-troubleshooting)
-- [Contributing](#-contributing)
 
-## ✨ Features
+- 🧠 **Advanced AI Integration**: Leverage OpenAI's powerful models (GPT-3.5, GPT-4) for smart home interactions
+- 💬 **Natural Language Control**: Control your home and get information using everyday language
+- 📝 **Conversation Memory**: Maintain context with conversation history tracking
+- ⚡ **Real-time Responses**: Get quick, contextual responses to your queries
+- 🎯 **Customizable Behavior**: Fine-tune AI responses with adjustable parameters
+- 🔒 **Secure Integration**: Your API key and data are handled securely
+- 🎨 **Flexible Configuration**: Easy setup with multiple configuration options
+- 🔄 **Automation Ready**: Integrate AI responses into your automations
 
-- 🔄 **Real-time AI Interaction**: Seamless communication with OpenAI's latest models
+## 📋 Prerequisites
-- 📝 **Conversation History**: Track and manage your AI interactions
-- ⚙️ **Customizable Settings**: Fine-tune AI behavior with adjustable parameters
-- 🔌 **Easy Integration**: Simple setup process through HACS or manual installation
-- 🎯 **System Prompts**: Set context for more relevant AI responses
 
-## 🚀 Installation
+- Home Assistant installation (Core, OS, Container, or Supervised)
+- OpenAI API key ([Get one here](https://platform.openai.com/account/api-keys))
+- Python 3.9 or newer
 
-### HACS Installation (Recommended)
+## ⚡ Quick Start
-1. Ensure [HACS](https://hacs.xyz/) is installed
-2. Search for "HA text AI" in HACS
-3. Click Install
-4. Restart Home Assistant
 
-<details>
+### Manual Installation
-<summary>Manual Installation Steps</summary>
+1. Download the repository
-
+2. Copy `custom_components/ha_text_ai` to your `custom_components` directory
-```bash
+3. Restart Home Assistant
-# 1. Navigate to your Home Assistant configuration directory
+4. Add configuration to `configuration.yaml`:
-cd ~/.homeassistant
-
-# 2. Create custom_components directory if it doesn't exist
-mkdir -p custom_components
-
-# 3. Clone the repository
-git clone https://github.com/smkrv/ha-text-ai.git custom_components/ha_text_ai
-
-# 4. Restart Home Assistant
-```
-</details>
-
-## ⚙️ Configuration
-
-### Basic Configuration
 ```yaml
 ha_text_ai:
-  api_key: your_openai_api_key
+  api_key: !secret openai_api_key
-  model: gpt-3.5-turbo
 ```
 
-### Advanced Configuration
+## ⚙️ Configuration Options
-```yaml
-ha_text_ai:
-  api_key: your_openai_api_key
-  model: gpt-4
-  temperature: 0.8
-  max_tokens: 2000
-  api_endpoint: https://custom-endpoint.com/v1
-  request_interval: 2.0
-```
 
-## 🛠 Services
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `api_key` | string | Required | Your OpenAI API key |
+| `model` | string | `gpt-3.5-turbo` | AI model to use |
+| `temperature` | float | `0.7` | Response creativity (0-2) |
+| `max_tokens` | integer | `1000` | Maximum response length |
+| `request_interval` | float | `1.0` | Minimum seconds between requests |
+| `api_endpoint` | string | OpenAI default | Custom API endpoint URL |
 
-### Ask Question
+## 🛠️ Available Services
+
+### ask_question
+Ask the AI assistant a question:
 ```yaml
 service: ha_text_ai.ask_question
 data:
-  question: "What's the weather like today?"
+  question: "What's the optimal temperature for sleeping?"
   model: "gpt-4"  # optional
-  temperature: 0.7  # optional
+  temperature: 0.5  # optional
+  max_tokens: 500  # optional
 ```
 
-### More Services
+### set_system_prompt
-- `ha_text_ai.clear_history`: Reset conversation history
+Configure AI behavior:
-- `ha_text_ai.get_history`: Retrieve past interactions
+```yaml
-- `ha_text_ai.set_system_prompt`: Configure AI behavior
+service: ha_text_ai.set_system_prompt
+data:
+  prompt: "You are a home automation expert focused on energy efficiency"
+```
 
-## 🔍 Advanced Usage
+### clear_history
+Reset conversation history:
+```yaml
+service: ha_text_ai.clear_history
+```
 
-### Automation Example
+### get_history
+Retrieve conversation history:
+```yaml
+service: ha_text_ai.get_history
+data:
+  limit: 5  # optional
+```
+
+## 🔧 Practical Examples
+
+### Smart Temperature Management
+```yaml
+automation:
+  trigger:
+    platform: time_pattern
+    hours: "/1"
+  action:
+    service: ha_text_ai.ask_question
+    data:
+      question: >
+        Current temperature is {{ states('sensor.living_room_temperature') }}°C.
+        Should I adjust the thermostat for optimal comfort and energy savings?
+```
+
+### Smart Lighting Assistant
 ```yaml
 automation:
   trigger:
     platform: state
-    entity_id: binary_sensor.motion
+    entity_id: binary_sensor.living_room_motion
     to: 'on'
+  condition:
+    condition: template
+    value_template: "{{ states('sensor.illuminance') | float < 10 }}"
   action:
     service: ha_text_ai.ask_question
     data:
-      question: "What should I do when motion is detected?"
+      question: >
+        Motion detected in living room with low light levels.
+        What's the best lighting scene to set based on the time of day?
 ```
 
-## 🔧 Troubleshooting
+## ❗ Common Issues
 
-<details>
+### API Rate Limits
-<summary>Common Issues and Solutions</summary>
+- Increase `request_interval` if hitting rate limits
+- Consider upgrading your OpenAI plan
+- Use caching for frequent queries
 
-### API Key Issues
+### High Token Usage
-- Verify API key format
+- Reduce `max_tokens` parameter
-- Check API key permissions
+- Clear conversation history regularly
-- Ensure proper configuration in secrets.yaml
+- Use focused system prompts
 
-### Connection Problems
+### Connection Issues
-- Verify internet connection
+- Check internet connectivity
-- Check API endpoint accessibility
+- Verify API key validity
-- Review Home Assistant logs
+- Ensure endpoint accessibility
-</details>
 
-## 👥 Contributing
+## 🤝 Contributing
 
-We welcome contributions! Here's how you can help:
+Contributions are welcome! Please feel free to submit a Pull Request.
 
 1. Fork the repository
-2. Create a feature branch
+2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
-3. Commit your changes
+3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
-4. Push to the branch
+4. Push to the branch (`git push origin feature/AmazingFeature`)
-5. Submit a pull request
+5. Open a Pull Request
+
+## 📝 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
 
 ---
 
 <div align="center">
 
-**[Documentation](https://github.com/smkrv/ha-text-ai/wiki)** | **[Report Bug](https://github.com/smkrv/ha-text-ai/issues)** | **[Request Feature](https://github.com/smkrv/ha-text-ai/issues)**
+Made with ❤️ for the Home Assistant Community
 
 </div>

custom_components/ha_text_ai/__init__.py

@@ -5,10 +5,10 @@ from typing import Any
 import voluptuous as vol
 
 from homeassistant.config_entries import ConfigEntry
-from homeassistant.const import CONF_API_KEY, Platform
+from homeassistant.const import CONF_API_KEY
 from homeassistant.core import HomeAssistant, ServiceCall
 import homeassistant.helpers.config_validation as cv
-from homeassistant.exceptions import HomeAssistantError
+from homeassistant.exceptions import HomeAssistantError, ConfigEntryNotReady
 
 from .const import (
     DOMAIN,
@@ -28,95 +28,80 @@ from .coordinator import HATextAICoordinator
 _LOGGER = logging.getLogger(__name__)
 
 async def async_setup(hass: HomeAssistant, config: dict[str, Any]) -> bool:
-    """Set up the HA text AI component from configuration.yaml."""
+    """Set up the HA text AI component."""
     hass.data.setdefault(DOMAIN, {})
 
     async def async_ask_question(call: ServiceCall) -> None:
-        """Handle the ask_question service call.
+        """Handle the ask_question service call."""
+        if not hass.data[DOMAIN]:
+            raise HomeAssistantError("No AI Text integration configured")
+
+        coordinator = next(iter(hass.data[DOMAIN].values()))
+        question = call.data["question"]
+
+ 
+        original_params = {
+            "model": coordinator.model,
+            "temperature": coordinator.temperature,
+            "max_tokens": coordinator.max_tokens
+        }
 
-        Args:
-            call: Service call containing question and optional parameters.
-        """
         try:
-            # Get the coordinator from the first config entry
-            if not hass.data[DOMAIN]:
-                raise HomeAssistantError("No AI Text integration configured")
 
-            coordinator = next(iter(hass.data[DOMAIN].values()))
+            if "model" in call.data:
+                coordinator.model = call.data["model"]
+            if "temperature" in call.data:
+                coordinator.temperature = call.data["temperature"]
+            if "max_tokens" in call.data:
+                coordinator.max_tokens = call.data["max_tokens"]
 
-            question = call.data["question"]
+            await coordinator.async_ask_question(question)
-            model = call.data.get("model", coordinator.model)
-            temperature = call.data.get("temperature", coordinator.temperature)
-            max_tokens = call.data.get("max_tokens", coordinator.max_tokens)
-
-            # Temporarily update parameters if they were overridden
-            original_model = coordinator.model
-            original_temperature = coordinator.temperature
-            original_max_tokens = coordinator.max_tokens
-
-            try:
-                coordinator.model = model
-                coordinator.temperature = temperature
-                coordinator.max_tokens = max_tokens
-                await coordinator.async_ask_question(question)
-            finally:
-                # Restore original parameters
-                coordinator.model = original_model
-                coordinator.temperature = original_temperature
-                coordinator.max_tokens = original_max_tokens
         except Exception as ex:
             _LOGGER.error("Error asking question: %s", str(ex))
-            raise HomeAssistantError(f"Failed to ask question: {str(ex)}")
+            raise HomeAssistantError(f"Failed to ask question: {str(ex)}") from ex
+        finally:
+
+            coordinator.model = original_params["model"]
+            coordinator.temperature = original_params["temperature"]
+            coordinator.max_tokens = original_params["max_tokens"]
 
     async def async_clear_history(call: ServiceCall) -> None:
         """Handle the clear_history service call."""
-        try:
+        if not hass.data[DOMAIN]:
-            if not hass.data[DOMAIN]:
+            raise HomeAssistantError("No AI Text integration configured")
-                raise HomeAssistantError("No AI Text integration configured")
 
-            coordinator = next(iter(hass.data[DOMAIN].values()))
+        coordinator = next(iter(hass.data[DOMAIN].values()))
-            coordinator._responses.clear()
+        coordinator._responses.clear()
-            await coordinator.async_refresh()
+        await coordinator.async_refresh()
-        except Exception as ex:
-            _LOGGER.error("Error clearing history: %s", str(ex))
-            raise HomeAssistantError(f"Failed to clear history: {str(ex)}")
 
     async def async_get_history(call: ServiceCall) -> dict[str, list]:
-        """Handle the get_history service call.
+        """Handle the get_history service call."""
+        if not hass.data[DOMAIN]:
+            raise HomeAssistantError("No AI Text integration configured")
 
-        Returns:
+        coordinator = next(iter(hass.data[DOMAIN].values()))
-            Dictionary containing chat history.
+        if not coordinator._responses:
-        """
+            return {"history": []}
-        try:
-            if not hass.data[DOMAIN]:
-                raise HomeAssistantError("No AI Text integration configured")
 
-            coordinator = next(iter(hass.data[DOMAIN].values()))
+        limit = call.data.get("limit", 10)
-            limit = call.data.get("limit", 10)
+        history = list(coordinator._responses.items())
-            history = list(coordinator._responses.items())[-limit:]
+        limited_history = history[-limit:] if len(history) > limit else history
-            return {
+
-                "history": [
+        return {
-                    {"question": q, "response": r} for q, r in history
+            "history": [
-                ]
+                {"question": q, "response": r} for q, r in limited_history
-            }
+            ]
-        except Exception as ex:
+        }
-            _LOGGER.error("Error getting history: %s", str(ex))
-            raise HomeAssistantError(f"Failed to get history: {str(ex)}")
 
     async def async_set_system_prompt(call: ServiceCall) -> None:
         """Handle the set_system_prompt service call."""
-        try:
+        if not hass.data[DOMAIN]:
-            if not hass.data[DOMAIN]:
+            raise HomeAssistantError("No AI Text integration configured")
-                raise HomeAssistantError("No AI Text integration configured")
+
+        coordinator = next(iter(hass.data[DOMAIN].values()))
+        coordinator.system_prompt = call.data["prompt"]
 
-            coordinator = next(iter(hass.data[DOMAIN].values()))
-            prompt = call.data["prompt"]
-            coordinator.system_prompt = prompt
-        except Exception as ex:
-            _LOGGER.error("Error setting system prompt: %s", str(ex))
-            raise HomeAssistantError(f"Failed to set system prompt: {str(ex)}")
 
-    # Register services
     hass.services.async_register(
         DOMAIN,
         SERVICE_ASK_QUESTION,
@@ -176,32 +161,28 @@ async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
         )
 
         await coordinator.async_config_entry_first_refresh()
-
         hass.data[DOMAIN][entry.entry_id] = coordinator
 
         return await hass.config_entries.async_forward_entry_setups(entry, PLATFORMS)
     except Exception as ex:
-        _LOGGER.error("Error setting up entry: %s", str(ex))
+        raise ConfigEntryNotReady(f"Failed to setup entry: {str(ex)}") from ex
-        raise ConfigEntryNotReady from ex
 
 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)
-        unload_ok = await hass.config_entries.async_unload_platforms(entry, PLATFORMS)
+    if unload_ok:
-        if unload_ok:
+        hass.data[DOMAIN].pop(entry.entry_id)
-            hass.data[DOMAIN].pop(entry.entry_id)
 
-            # Only remove services if this is the last entry
+
-            if not hass.data[DOMAIN]:
+        if not hass.data[DOMAIN]:
-                for service in [
+            services = [
-                    SERVICE_ASK_QUESTION,
+                SERVICE_ASK_QUESTION,
-                    SERVICE_CLEAR_HISTORY,
+                SERVICE_CLEAR_HISTORY,
-                    SERVICE_GET_HISTORY,
+                SERVICE_GET_HISTORY,
-                    SERVICE_SET_SYSTEM_PROMPT
+                SERVICE_SET_SYSTEM_PROMPT
-                ]:
+            ]
+            for service in services:
+                if service in hass.services.async_services().get(DOMAIN, {}):
                     hass.services.async_remove(DOMAIN, service)
 
-        return unload_ok
+    return unload_ok
-    except Exception as ex:
-        _LOGGER.error("Error unloading entry: %s", str(ex))
-        return False

custom_components/ha_text_ai/config_flow.py

@@ -1,8 +1,12 @@
 """Config flow for HA text AI integration."""
+from typing import Any, Dict, Optional
 import voluptuous as vol
+
 from homeassistant import config_entries
+from homeassistant.const import CONF_API_KEY
 import homeassistant.helpers.config_validation as cv
 from homeassistant.core import callback
+import openai
 
 from .const import (
     DOMAIN,
@@ -18,70 +22,117 @@ from .const import (
     DEFAULT_REQUEST_INTERVAL,
 )
 
-class HATextAIConfigFlow(config_entries.ConfigFlow):
+STEP_USER_DATA_SCHEMA = vol.Schema({
+    vol.Required(CONF_API_KEY): str,
+    vol.Optional(CONF_MODEL, default=DEFAULT_MODEL): str,
+    vol.Optional(
+        CONF_TEMPERATURE,
+        default=DEFAULT_TEMPERATURE
+    ): vol.All(vol.Coerce(float), vol.Range(min=0, max=2)),
+    vol.Optional(
+        CONF_MAX_TOKENS,
+        default=DEFAULT_MAX_TOKENS
+    ): vol.All(vol.Coerce(int), vol.Range(min=1, max=4096)),
+    vol.Optional(CONF_API_ENDPOINT, default=DEFAULT_API_ENDPOINT): str,
+    vol.Optional(
+        CONF_REQUEST_INTERVAL,
+        default=DEFAULT_REQUEST_INTERVAL
+    ): vol.All(vol.Coerce(float), vol.Range(min=0.1)),
+})
+
+class HATextAIConfigFlow(config_entries.ConfigFlow, domain=DOMAIN):
     """Handle a config flow for HA text AI."""
 
     VERSION = 1
-    DOMAIN = DOMAIN  # Define the domain as a class variable
 
-    async def async_step_user(self, user_input=None):
+    async def async_step_user(
+        self,
+        user_input: Optional[Dict[str, Any]] = None
+    ) -> Dict[str, Any]:
         """Handle the initial step."""
-        errors = {}
+        errors: Dict[str, str] = {}
 
         if user_input is not None:
-            return self.async_create_entry(title="HA text AI", data=user_input)
+            try:
+ 
+                client = openai.OpenAI(
+                    api_key=user_input[CONF_API_KEY],
+                    base_url=user_input.get(CONF_API_ENDPOINT, DEFAULT_API_ENDPOINT)
+                )
+                await self.hass.async_add_executor_job(
+                    client.models.list
+                )
+
+
+                await self.async_set_unique_id(user_input[CONF_API_KEY])
+                self._abort_if_unique_id_configured()
+
+                return self.async_create_entry(
+                    title="HA text AI",
+                    data=user_input
+                )
+
+            except openai.AuthenticationError:
+                errors["base"] = "invalid_auth"
+            except openai.APIError:
+                errors["base"] = "cannot_connect"
+            except Exception:  # pylint: disable=broad-except
+                errors["base"] = "unknown"
 
         return self.async_show_form(
             step_id="user",
-            data_schema=vol.Schema({
+            data_schema=STEP_USER_DATA_SCHEMA,
-                vol.Required("api_key"): str,
-                vol.Optional(CONF_MODEL, default=DEFAULT_MODEL): str,
-                vol.Optional(CONF_TEMPERATURE, default=DEFAULT_TEMPERATURE): vol.Coerce(float),
-                vol.Optional(CONF_MAX_TOKENS, default=DEFAULT_MAX_TOKENS): vol.Coerce(int),
-                vol.Optional(CONF_API_ENDPOINT, default=DEFAULT_API_ENDPOINT): str,
-                vol.Optional(CONF_REQUEST_INTERVAL, default=DEFAULT_REQUEST_INTERVAL): vol.Coerce(float),
-            }),
             errors=errors,
         )
 
     @staticmethod
     @callback
-    def async_get_options_flow(config_entry):
+    def async_get_options_flow(
+        config_entry: config_entries.ConfigEntry,
+    ) -> config_entries.OptionsFlow:
         """Get the options flow for this handler."""
         return OptionsFlowHandler(config_entry)
 
 class OptionsFlowHandler(config_entries.OptionsFlow):
     """Handle options flow for HA text AI."""
 
-    def __init__(self, config_entry):
+    def __init__(self, config_entry: config_entries.ConfigEntry) -> None:
         """Initialize options flow."""
         self.config_entry = config_entry
 
-    async def async_step_init(self, user_input=None):
+    async def async_step_init(
+        self,
+        user_input: Optional[Dict[str, Any]] = None
+    ) -> Dict[str, Any]:
         """Handle options flow."""
         if user_input is not None:
             return self.async_create_entry(title="", data=user_input)
 
+        options_schema = vol.Schema({
+            vol.Optional(
+                CONF_TEMPERATURE,
+                default=self.config_entry.options.get(
+                    CONF_TEMPERATURE, DEFAULT_TEMPERATURE
+                ),
+                description="Temperature for response generation (0-2)",
+            ): vol.All(vol.Coerce(float), vol.Range(min=0, max=2)),
+            vol.Optional(
+                CONF_MAX_TOKENS,
+                default=self.config_entry.options.get(
+                    CONF_MAX_TOKENS, DEFAULT_MAX_TOKENS
+                ),
+                description="Maximum tokens in response (1-4096)",
+            ): vol.All(vol.Coerce(int), vol.Range(min=1, max=4096)),
+            vol.Optional(
+                CONF_REQUEST_INTERVAL,
+                default=self.config_entry.options.get(
+                    CONF_REQUEST_INTERVAL, DEFAULT_REQUEST_INTERVAL
+                ),
+                description="Minimum time between API requests (seconds)",
+            ): vol.All(vol.Coerce(float), vol.Range(min=0.1)),
+        })
+
         return self.async_show_form(
             step_id="init",
-            data_schema=vol.Schema({
+            data_schema=options_schema,
-                vol.Optional(
-                    CONF_TEMPERATURE,
-                    default=self.config_entry.options.get(
-                        CONF_TEMPERATURE, DEFAULT_TEMPERATURE
-                    ),
-                ): vol.Coerce(float),
-                vol.Optional(
-                    CONF_MAX_TOKENS,
-                    default=self.config_entry.options.get(
-                        CONF_MAX_TOKENS, DEFAULT_MAX_TOKENS
-                    ),
-                ): vol.Coerce(int),
-                vol.Optional(
-                    CONF_REQUEST_INTERVAL,
-                    default=self.config_entry.options.get(
-                        CONF_REQUEST_INTERVAL, DEFAULT_REQUEST_INTERVAL
-                    ),
-                ): vol.Coerce(float),
-            }),
         )

custom_components/ha_text_ai/const.py

@@ -1,30 +1,61 @@
 """Constants for the HA text AI integration."""
+from typing import Final
 from homeassistant.const import Platform
 
-DOMAIN = "ha_text_ai"
+# Domain
-PLATFORMS = [Platform.SENSOR]
+DOMAIN: Final = "ha_text_ai"
+PLATFORMS: Final = [Platform.SENSOR]
 
-# Configuration
+# Configuration constants
-CONF_MODEL = "model"
+CONF_MODEL: Final = "model"
-CONF_TEMPERATURE = "temperature"
+CONF_TEMPERATURE: Final = "temperature"
-CONF_MAX_TOKENS = "max_tokens"
+CONF_MAX_TOKENS: Final = "max_tokens"
-CONF_API_ENDPOINT = "api_endpoint"
+CONF_API_ENDPOINT: Final = "api_endpoint"
-CONF_REQUEST_INTERVAL = "request_interval"
+CONF_REQUEST_INTERVAL: Final = "request_interval"
 
-# Defaults
+# Default values
-DEFAULT_MODEL = "gpt-3.5-turbo"
+DEFAULT_MODEL: Final = "gpt-3.5-turbo"
-DEFAULT_TEMPERATURE = 0.7
+DEFAULT_TEMPERATURE: Final = 0.7
-DEFAULT_MAX_TOKENS = 1000
+DEFAULT_MAX_TOKENS: Final = 1000
-DEFAULT_API_ENDPOINT = "https://api.openai.com/v1"
+DEFAULT_API_ENDPOINT: Final = "https://api.openai.com/v1"
-DEFAULT_REQUEST_INTERVAL = 1.0
+DEFAULT_REQUEST_INTERVAL: Final = 1.0
 
-# Services
+# Parameter constraints
-SERVICE_ASK_QUESTION = "ask_question"
+MIN_TEMPERATURE: Final = 0.0
-SERVICE_CLEAR_HISTORY = "clear_history"
+MAX_TEMPERATURE: Final = 2.0
-SERVICE_GET_HISTORY = "get_history"
+MIN_MAX_TOKENS: Final = 1
-SERVICE_SET_SYSTEM_PROMPT = "set_system_prompt"
+MAX_MAX_TOKENS: Final = 4096
+MIN_REQUEST_INTERVAL: Final = 0.1
 
-# Attributes
+# Service names
-ATTR_QUESTION = "question"
+SERVICE_ASK_QUESTION: Final = "ask_question"
-ATTR_RESPONSE = "response"
+SERVICE_CLEAR_HISTORY: Final = "clear_history"
-ATTR_LAST_UPDATED = "last_updated"
+SERVICE_GET_HISTORY: Final = "get_history"
+SERVICE_SET_SYSTEM_PROMPT: Final = "set_system_prompt"
+
+# Service descriptions
+SERVICE_ASK_QUESTION_DESCRIPTION: Final = "Ask a question to the AI model"
+SERVICE_CLEAR_HISTORY_DESCRIPTION: Final = "Clear conversation history"
+SERVICE_GET_HISTORY_DESCRIPTION: Final = "Get conversation history"
+SERVICE_SET_SYSTEM_PROMPT_DESCRIPTION: Final = "Set system prompt for AI model"
+
+# Attribute keys
+ATTR_QUESTION: Final = "question"
+ATTR_RESPONSE: Final = "response"
+ATTR_LAST_UPDATED: Final = "last_updated"
+
+# Error messages
+ERROR_INVALID_API_KEY: Final = "invalid_api_key"
+ERROR_CANNOT_CONNECT: Final = "cannot_connect"
+ERROR_UNKNOWN: Final = "unknown_error"
+
+# Configuration descriptions
+CONF_MODEL_DESCRIPTION: Final = "AI model to use for responses"
+CONF_TEMPERATURE_DESCRIPTION: Final = "Temperature for response generation (0-2)"
+CONF_MAX_TOKENS_DESCRIPTION: Final = "Maximum tokens in response (1-4096)"
+CONF_API_ENDPOINT_DESCRIPTION: Final = "API endpoint URL"
+CONF_REQUEST_INTERVAL_DESCRIPTION: Final = "Minimum time between API requests (seconds)"
+
+# Entity attributes
+ENTITY_NAME: Final = "HA Text AI"
+ENTITY_ICON: Final = "mdi:robot"

custom_components/ha_text_ai/coordinator.py

@@ -1,21 +1,51 @@
+"""The HA Text AI integration."""
+from homeassistant.config_entries import ConfigEntry
+from homeassistant.core import HomeAssistant
+from homeassistant.exceptions import ConfigEntryNotReady
+from .const import DOMAIN, PLATFORMS
+from .coordinator import HATextAICoordinator
+
+async def async_setup_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
+    """Set up HA Text AI from a config entry."""
+    try:
+        coordinator = HATextAICoordinator(
+            hass,
+            api_key=entry.data["api_key"],
+            endpoint=entry.data.get("api_endpoint", "https://api.openai.com/v1"),
+            model=entry.data.get("model", "gpt-3.5-turbo"),
+            temperature=entry.data.get("temperature", 0.7),
+            max_tokens=entry.data.get("max_tokens", 1000),
+            request_interval=entry.data.get("request_interval", 1.0),
+        )
+
+        await coordinator.async_config_entry_first_refresh()
+
+        hass.data.setdefault(DOMAIN, {})
+        hass.data[DOMAIN][entry.entry_id] = coordinator
+
+        return await hass.config_entries.async_forward_entry_setups(entry, PLATFORMS)
+    except Exception as ex:
+        raise ConfigEntryNotReady(f"Failed to setup entry: {str(ex)}") from ex
+
+async def async_unload_entry(hass: HomeAssistant, entry: ConfigEntry) -> bool:
+    """Unload a config entry."""
+    unload_ok = await hass.config_entries.async_unload_platforms(entry, PLATFORMS)
+    if unload_ok:
+        hass.data[DOMAIN].pop(entry.entry_id)
+    return unload_ok
+
 """Data coordinator for HA text AI."""
 import asyncio
 import logging
 from datetime import timedelta
-from typing import Any, Dict
+from typing import Any, Dict, Optional
 
 import openai
 from homeassistant.core import HomeAssistant
 from homeassistant.helpers.update_coordinator import DataUpdateCoordinator
 from homeassistant.exceptions import ConfigEntryAuthFailed
 
-from .const import (
+from .const import DOMAIN
-    DOMAIN,
-    DEFAULT_REQUEST_INTERVAL,
-    CONF_MODEL,
-    CONF_TEMPERATURE,
-    CONF_MAX_TOKENS,
-)
 
 _LOGGER = logging.getLogger(__name__)
 
@@ -40,18 +70,26 @@ class HATextAICoordinator(DataUpdateCoordinator):
             update_interval=timedelta(seconds=request_interval),
         )
 
+        if not api_key:
+            raise ValueError("API key is required")
+        if not isinstance(temperature, (int, float)) or not 0 <= temperature <= 2:
+            raise ValueError("Temperature must be between 0 and 2")
+        if not isinstance(max_tokens, int) or max_tokens < 1:
+            raise ValueError("Max tokens must be a positive integer")
+
         self.api_key = api_key
-        self.endpoint = endpoint
+        self.endpoint = endpoint or "https://api.openai.com/v1"
-        self.model = model
+        self.model = model or "gpt-3.5-turbo"
-        self.temperature = temperature
+        self.temperature = float(temperature)
-        self.max_tokens = max_tokens
+        self.max_tokens = int(max_tokens)
         self._question_queue = asyncio.Queue()
         self._responses: Dict[str, Any] = {}
         self.system_prompt: Optional[str] = None
 
-        openai.api_key = self.api_key
+        self.client = openai.OpenAI(
-        if endpoint != "https://api.openai.com/v1":
+            api_key=self.api_key,
-            openai.api_base = endpoint
+            base_url=self.endpoint
+        )
 
     async def _async_update_data(self) -> Dict[str, Any]:
         """Update data via OpenAI API."""
@@ -63,15 +101,14 @@ class HATextAICoordinator(DataUpdateCoordinator):
             response_content = await self.hass.async_add_executor_job(
                 self._make_api_call, question
             )
-            response = {
+            self._responses[question] = {
                 "question": question,
                 "response": response_content
             }
-            self._responses[question] = response
+            _LOGGER.debug("Response from API: %s", response_content)
-            _LOGGER.debug(f"Response from API: {response}")
             return self._responses
 
-        except openai.error.AuthenticationError as err:
+        except openai.AuthenticationError as err:
             raise ConfigEntryAuthFailed from err
         except Exception as err:
             _LOGGER.error("Error communicating with API: %s", err)
@@ -80,9 +117,12 @@ class HATextAICoordinator(DataUpdateCoordinator):
     def _make_api_call(self, question: str) -> str:
         """Make API call to OpenAI."""
         try:
-            messages = [{"role": "system", "content": self.system_prompt}] if self.system_prompt else []
+            messages = []
+            if self.system_prompt:
+                messages.append({"role": "system", "content": self.system_prompt})
             messages.append({"role": "user", "content": question})
-            completion = openai.chat.completions.create(
+
+            completion = self.client.chat.completions.create(
                 model=self.model,
                 messages=messages,
                 temperature=self.temperature,
@@ -92,23 +132,3 @@ class HATextAICoordinator(DataUpdateCoordinator):
         except Exception as err:
             _LOGGER.error("Error in API call: %s", err)
             raise
-
-    async def async_ask_question(self, question: str) -> None:
-        """Add question to queue."""
-        await self._question_queue.put(question)
-        _LOGGER.debug(f"Question added to queue: {question}")
-        await self.async_refresh()
-
-    def clear_history(self) -> None:
-        """Clear the stored question and response history."""
-        self._responses.clear()
-        _LOGGER.info("History cleared.")
-
-    def get_history(self, limit: int = 10) -> Dict[str, Any]:
-        """Get the history of questions and responses."""
-        return {"history": list(self._responses.values())[-limit:]}
-
-    def set_system_prompt(self, prompt: str) -> None:
-        """Set a system prompt that will be used for all future questions."""
-        self.system_prompt = prompt
-        _LOGGER.info(f"System prompt set: {prompt}")

custom_components/ha_text_ai/manifest.json

@@ -1,15 +1,14 @@
 {
   "domain": "ha_text_ai",
-  "name": "HA text AI",
+  "name": "HA Text AI",
   "config_flow": true,
-  "documentation": "https://github.com/smkrv/ha-text-ai",
+  "documentation": "https://github.com/smkrv/ha-text-ai/wiki",
   "issue_tracker": "https://github.com/smkrv/ha-text-ai/issues",
   "requirements": ["openai>=1.0.0"],
   "ssdp": [],
   "zeroconf": [],
-  "homekit": {},
   "dependencies": [],
-  "codeowners": ["@smkrv"],
+  "version": "1.0.1c",
-  "version": "1.0.1b",
+  "iot_class": "cloud_polling",
-  "iot_class": "cloud_polling"
+  "codeowners": ["@smkrv"]
 }

custom_components/ha_text_ai/sensor.py

@@ -1,7 +1,13 @@
 """Sensor platform for HA text AI."""
+from datetime import datetime
+import logging
 from typing import Any, Callable, Dict, Optional
 
-from homeassistant.components.sensor import SensorEntity, SensorStateClass
+from homeassistant.components.sensor import (
+    SensorEntity,
+    SensorStateClass,
+    SensorDeviceClass,
+)
 from homeassistant.config_entries import ConfigEntry
 from homeassistant.core import HomeAssistant
 from homeassistant.helpers.entity_platform import AddEntitiesCallback
@@ -11,6 +17,8 @@ from homeassistant.helpers.update_coordinator import CoordinatorEntity
 from .const import DOMAIN, ATTR_QUESTION, ATTR_RESPONSE, ATTR_LAST_UPDATED
 from .coordinator import HATextAICoordinator
 
+_LOGGER = logging.getLogger(__name__)
+
 async def async_setup_entry(
     hass: HomeAssistant,
     entry: ConfigEntry,
@@ -23,6 +31,11 @@ async def async_setup_entry(
 class HATextAISensor(CoordinatorEntity, SensorEntity):
     """HA text AI Sensor."""
 
+    _attr_has_entity_name = True
+    _attr_state_class = SensorStateClass.MEASUREMENT
+    _attr_device_class = SensorDeviceClass.TIMESTAMP
+    _attr_icon = "mdi:robot"
+
     def __init__(
         self,
         coordinator: HATextAICoordinator,
@@ -32,27 +45,50 @@ class HATextAISensor(CoordinatorEntity, SensorEntity):
         super().__init__(coordinator)
         self._config_entry = config_entry
         self._attr_unique_id = f"{config_entry.entry_id}"
-        self._attr_name = "HA text AI"
+        self._attr_name = "Last Response"
-        self._attr_state_class = SensorStateClass.MEASUREMENT
 
     @property
     def state(self) -> StateType:
         """Return the state of the sensor."""
-        if self.coordinator.data:
+        if not self.coordinator.data:
-            return "Ready"  # Assuming "Ready" is a valid state, you might want to return something meaningful, like the last response time.
+            return None
-        return "Not Ready"
+        return self.coordinator.last_update_success_time
 
     @property
     def extra_state_attributes(self) -> Optional[Dict[str, Any]]:
         """Return entity specific state attributes."""
         if not self.coordinator.data:
             return None
-        keys = list(self.coordinator.data.keys())
+
-        values = list(self.coordinator.data.values())
+        try:
-        last_question = keys[-1]
+
-        last_response = values[-1]
+            history = list(self.coordinator.data.items())
-        return {
+            if not history:
-            ATTR_QUESTION: last_question,
+                return None
-            ATTR_RESPONSE: last_response,
+
-            ATTR_LAST_UPDATED: self.coordinator.last_update_success_time,
+            last_question, last_data = history[-1]
-        }
+
+
+            if isinstance(last_data, dict):
+                last_response = last_data.get("response", "")
+            else:
+                last_response = str(last_data)
+
+            return {
+                ATTR_QUESTION: last_question,
+                ATTR_RESPONSE: last_response,
+                ATTR_LAST_UPDATED: self.coordinator.last_update_success_time,
+            }
+        except (IndexError, KeyError, AttributeError) as err:
+            _LOGGER.warning("Error getting attributes: %s", err)
+            return None
+
+    @property
+    def available(self) -> bool:
+        """Return if entity is available."""
+        return self.coordinator.last_update_success
+
+    @property
+    def should_poll(self) -> bool:
+        """No need to poll. Coordinator notifies entity of updates."""
+        return False

custom_components/ha_text_ai/services.yaml

@@ -1,63 +1,76 @@
 ask_question:
   name: Ask Question
-  description: Send a question to the AI and get a response
+  description: Send a question to the AI model and receive a detailed response
   fields:
     question:
       name: Question
-      description: The question or prompt to send to the AI
+      description: Your question or prompt for the AI assistant
       required: true
-      example: "What is the weather like today?"
+      example: "What automations would you recommend for a smart kitchen?"
       selector:
         text:
           multiline: true
+          type: text
 
     model:
       name: Model
-      description: Override the default model for this question (optional)
+      description: Select an AI model to use (optional, overrides default setting)
       required: false
-      example: "gpt-4"
+      example: "gpt-3.5-turbo"
       default: "gpt-3.5-turbo"
       selector:
         select:
           options:
-            - "gpt-3.5-turbo"
+            - label: "GPT-3.5 Turbo"
-            - "gpt-4"
+              value: "gpt-3.5-turbo"
-            - "gpt-4-32k"
+              icon: "mdi:rocket-launch"
+            - label: "GPT-4"
+              value: "gpt-4"
+              icon: "mdi:brain"
+            - label: "GPT-4 32K"
+              value: "gpt-4-32k"
+              icon: "mdi:brain-circuit"
 
     temperature:
       name: Temperature
-      description: Control randomness in the response (0.0-1.0, lower is more focused)
+      description: >-
+        Controls response creativity (0-2):
+        Lower values (0-0.7) for focused, consistent responses
+        Higher values (0.7-2.0) for more creative, varied responses
       required: false
       default: 0.7
       selector:
         number:
           min: 0.0
-          max: 1.0
+          max: 2.0
           step: 0.1
+          mode: slider
+          unit_of_measurement: ""
 
     max_tokens:
       name: Max Tokens
-      description: Maximum length of the response
+      description: Maximum length of the response (longer responses use more tokens)
       required: false
       default: 1000
       selector:
         number:
           min: 1
-          max: 4000
+          max: 4096
           step: 1
+          mode: box
 
 clear_history:
   name: Clear History
-  description: Clear the stored question and response history
+  description: Delete all stored questions and responses from the conversation history
   fields: {}
 
 get_history:
   name: Get History
-  description: Get the history of questions and responses
+  description: Retrieve recent conversation history between you and the AI
   fields:
     limit:
       name: Limit
-      description: Maximum number of history items to return
+      description: Number of most recent conversations to return
       required: false
       default: 10
       selector:
@@ -65,16 +78,26 @@ get_history:
           min: 1
           max: 100
           step: 1
+          mode: box
 
 set_system_prompt:
   name: Set System Prompt
-  description: Set a system prompt that will be used for all future questions
+  description: >-
+    Configure the AI's behavior by setting a system prompt that will be used
+    for all future conversations until changed
   fields:
     prompt:
       name: System Prompt
-      description: The system prompt to set
+      description: >-
+        Instructions that define how the AI should behave and respond.
+        This affects all future conversations.
       required: true
-      example: "You are a helpful assistant specializing in home automation"
+      example: >-
+        You are a home automation expert assistant. Provide practical advice
+        focused on smart home technology and automation. Use clear, concise
+        language and include specific product recommendations when relevant.
       selector:
         text:
           multiline: true
+          type: text
+          rows: 4

custom_components/ha_text_ai/translations/en.json

@@ -3,34 +3,76 @@
     "step": {
       "user": {
         "title": "Set up HA text AI",
-        "description": "Set up your OpenAI integration",
+        "description": "Configure your OpenAI integration for smart home interactions",
         "data": {
-          "api_key": "API Key",
+          "api_key": {
-          "model": "Model",
+            "name": "API Key",
-          "temperature": "Temperature",
+            "description": "Your OpenAI API key (starts with 'sk-')"
-          "max_tokens": "Max Tokens",
+          },
-          "api_endpoint": "API Endpoint",
+          "model": {
-          "request_interval": "Request Interval (seconds)"
+            "name": "AI Model",
+            "description": "Select the AI model to use (e.g., gpt-3.5-turbo)"
+          },
+          "temperature": {
+            "name": "Temperature",
+            "description": "Response creativity (0-2): lower for focused, higher for creative responses"
+          },
+          "max_tokens": {
+            "name": "Max Tokens",
+            "description": "Maximum response length (1-4096 tokens)"
+          },
+          "api_endpoint": {
+            "name": "API Endpoint",
+            "description": "OpenAI API endpoint URL (leave default if unsure)"
+          },
+          "request_interval": {
+            "name": "Request Interval",
+            "description": "Minimum time between API requests in seconds (0.1 or higher)"
+          }
         }
       }
     },
     "error": {
-      "auth": "API key is invalid.",
+      "invalid_auth": "Invalid API key. Please check your OpenAI API key and try again.",
-      "cannot_connect": "Failed to connect to API.",
+      "cannot_connect": "Failed to connect to API. Please check your internet connection and API endpoint.",
-      "unknown": "Unexpected error occurred."
+      "unknown": "Unexpected error occurred. Please check the logs for more details.",
+      "already_exists": "This API key is already configured in another integration."
     },
     "abort": {
-      "already_configured": "Device is already configured"
+      "already_configured": "This OpenAI integration is already configured",
+      "auth_failed": "Authentication failed. Please verify your API key."
     }
   },
   "options": {
     "step": {
       "init": {
         "title": "HA text AI Options",
+        "description": "Adjust your OpenAI integration settings",
         "data": {
-          "temperature": "Temperature",
+          "temperature": {
-          "max_tokens": "Max Tokens",
+            "name": "Temperature",
-          "request_interval": "Request Interval (seconds)"
+            "description": "Controls response creativity (0-2): lower values for focused responses, higher for more creative ones"
+          },
+          "max_tokens": {
+            "name": "Max Tokens",
+            "description": "Maximum length of responses (1-4096 tokens)"
+          },
+          "request_interval": {
+            "name": "Request Interval",
+            "description": "Minimum time between API requests in seconds (0.1 or higher)"
+          }
+        }
+      }
+    }
+  },
+  "entity": {
+    "sensor": {
+      "last_response": {
+        "name": "Last Response",
+        "state_attributes": {
+          "question": "Last Question",
+          "response": "AI Response",
+          "last_updated": "Last Updated"
         }
       }
     }

hacs.json

@@ -2,7 +2,7 @@
   "name": "HA text AI",
   "render_readme": true,
   "domains": ["sensor"],
-  "homeassistant": "2024.11.2",
+  "homeassistant": "2024.11.0",
   "icon": "mdi:brain",
   "version": "1.0.1b",
   "documentation": "https://github.com/smkrv/ha-text-ai"