Hass/ha-text-ai
1
0
Fork 0
mirror of https://github.com/smkrv/ha-text-ai.git synced 2026-07-21 22:54:00 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: Fix sensor attribute examples, refresh model lineup, strip filler from README

Browse Source
This commit is contained in:
SMKRV
2026-07-13 00:40:45 +03:00
parent 3cd8d3076a
commit 990134bde5
1 changed files with 173 additions and 253 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+171 -251
View File
@@ -1,4 +1,4 @@
# 🤖 HA Text AI for Home Assistant # HA Text AI for Home Assistant
<div align="center"> <div align="center">
@@ -8,180 +8,111 @@
<img src="https://github.com/smkrv/ha-text-ai/blob/main/custom_components/ha_text_ai/icons/logo%402x.png" alt="HA Text AI" style="width: 50%; max-width: 256px; max-height: 128px; aspect-ratio: 2/1; object-fit: contain;"/> <img src="https://github.com/smkrv/ha-text-ai/blob/main/custom_components/ha_text_ai/icons/logo%402x.png" alt="HA Text AI" style="width: 50%; max-width: 256px; max-height: 128px; aspect-ratio: 2/1; object-fit: contain;"/>
### Advanced AI Integration for [Home Assistant](https://www.home-assistant.io/) with LLM multi-provider support ### Multi-provider LLM integration for [Home Assistant](https://www.home-assistant.io/)
</div> </div>
<p align="center"> <p align="center">
Transform your smart home experience with powerful AI assistance powered by multiple AI providers including OpenAI GPT, Anthropic Claude, DeepSeek and Google Gemini models. Get intelligent responses, automate complex scenarios, and enhance your home automation with advanced natural language processing. Ask OpenAI, Anthropic Claude, DeepSeek and Google Gemini models questions from your automations and scripts. The integration keeps per-instance conversation history, returns full-length responses through response variables, supports structured JSON output, and exposes token, latency and error metrics as sensor attributes.
</p> </p>
--- ---
> [!IMPORTANT] > [!IMPORTANT]
> 🤝 Community Driven: for more details on the integration, > Community driven: for more details on the integration,
> check out the discussion on the **[Home Assistant Community forum](https://community.home-assistant.io/t/ha-text-ai-transforming-home-automation-through-multi-llm-integration/799741)** > check out the discussion on the **[Home Assistant Community forum](https://community.home-assistant.io/t/ha-text-ai-transforming-home-automation-through-multi-llm-integration/799741)**
> >
> <a href="https://my.home-assistant.io/redirect/hacs_repository/?owner=smkrv&repository=ha-text-ai&category=Integration"><img src="https://my.home-assistant.io/badges/hacs_repository.svg" width="210" height="auto"></a> > <a href="https://my.home-assistant.io/redirect/hacs_repository/?owner=smkrv&repository=ha-text-ai&category=Integration"><img src="https://my.home-assistant.io/badges/hacs_repository.svg" width="210" height="auto"></a>
> >
> [Screenshots](assets/images/screenshots/screenshot.jpg) > [Screenshots](assets/images/screenshots/screenshot.jpg)
## 🌟 Features ## Features
- 🧠 **Multi-Provider AI Integration**: Support for OpenAI GPT, Anthropic Claude, DeepSeek and Google Gemini models - **Multi-provider support**: OpenAI, Anthropic Claude, DeepSeek, Google Gemini, plus any OpenAI-compatible endpoint
- 💬 **Advanced Language Processing**: Context-aware, multi-turn conversations - **Conversation context**: the model sees previous messages; depth is configurable per request (1-20)
- 📝 **Enhanced Memory Management**: Secure file-based history storage - **Response variables**: `ask_question` returns the full response directly to the calling automation, bypassing the 255-character state limit
- ⚡ **Performance Optimization**: Efficient token usage and smart rate limiting - **Structured output**: JSON responses matching a schema you provide
- 🎯 **Advanced Customization**: Per-request model and parameter selection - **Per-request overrides**: model, temperature, max_tokens, system prompt, thinking mode
- 🔒 **Enhanced Security**: Secure API key management and usage monitoring - **Usage metrics**: token counters, latency and success/error statistics as sensor attributes
- 🎨 **Improved User Experience**: Intuitive configuration and rich interfaces - **File-based history**: per-instance JSON storage with automatic rotation at 1 MB
- 🔄 **Automation Integration**: Event-driven responses and template compatibility
<details> #### Translations
<summary>📦 Detailed Feature Breakdown</summary>
### 🧠 **Multi-Provider AI Integration**
- Support for OpenAI GPT models
- Anthropic Claude integration
- DeepSeek integration
- Google Gemini integration
- Custom API endpoints
- Flexible model selection
### 💬 **Advanced Language Processing**
- Context-aware responses
- Multi-turn conversations
- Custom system instructions
- Natural conversation flow
### 📝 **Enhanced Memory Management**
- File-based conversation history storage
- Automatic history rotation
- Configurable history size limits
- Secure storage in Home Assistant
### ⚡ **Performance Optimization**
- Efficient token usage
- Smart rate limiting
- Response caching
- Request interval control
### 🎯 **Advanced Customization**
- Per-request model selection
- Adjustable parameters
- Custom system prompts
- Temperature control
### 🔒 **Enhanced Security**
- Secure API key storage
- Rate limiting protection
- Error handling
- Usage monitoring
### 🎨 **Improved User Experience**
- Intuitive configuration UI
- Detailed sensor attributes
- Rich service interface
- Model selection UI
### 🔄 **Automation Integration**
- Event-driven responses
- Conditional logic support
- Template compatibility
- Model-specific automation
</details>
#### 🌐 Translations
| Code | Language | Status | | Code | Language | Status |
|------|----------|--------| |------|----------|--------|
| 🇩🇪 de | Deutsch | Full | | de | Deutsch | Full |
| 🇬🇧 en | English | Primary | | en | English | Primary |
| 🇪🇸 es | Español | Full | | es | Español | Full |
| 🇮🇳 hi | हिन्दी | Full | | hi | हिन्दी | Full |
| 🇮🇹 it | Italiano | Full | | it | Italiano | Full |
| 🇷🇺 ru | Русский | Full | | ru | Русский | Full |
| 🇷🇸 sr | Српски | Full | | sr | Српски | Full |
| 🇨🇳 zh | 中文 | Full | | zh | 中文 | Full |
## 📋 Prerequisites ## Prerequisites
- Home Assistant 2024.12.0 or later (recommended for best compatibility) - Home Assistant 2024.12.0 or later
- Active API key from: - An API key from one of:
- OpenAI ([Get key](https://platform.openai.com/account/api-keys)) - OpenAI ([Get key](https://platform.openai.com/account/api-keys))
- Anthropic ([Get key](https://console.anthropic.com/)) - Anthropic ([Get key](https://console.anthropic.com/))
- DeepSeek ([Get key](https://platform.deepseek.com/api_keys)) - DeepSeek ([Get key](https://platform.deepseek.com/api_keys))
- OpenRouter ([Get key](https://openrouter.ai/keys)) - OpenRouter ([Get key](https://openrouter.ai/keys))
- Google Gemini 🆕 ([Get key](https://ai.google.dev/gemini-api/docs/api-key)) thanks to ([@Azzedde](https://github.com/Azzedde)) - Google Gemini ([Get key](https://ai.google.dev/gemini-api/docs/api-key)) thanks to ([@Azzedde](https://github.com/Azzedde))
- Any OpenAI-compatible API provider - Any OpenAI-compatible API provider
- Python 3.9 or newer
- Stable internet connection
## Configuration Options ## Configuration Options
### 🔧 **Core Configuration Settings** ### Core Configuration Settings
- 🌐 **API Provider**: OpenAI/Anthropic/DeepSeek/Gemini - **API Provider**: OpenAI / Anthropic / DeepSeek / Gemini
- 🔑 **API Key**: Provider-specific authentication - **API Key**: provider-specific authentication
- 🤖 **Model Selection**: Flexible, provider-specific models - **Model**: any model your provider offers
- 🌡️ **Temperature**: Creativity control (0.0-2.0) - **Temperature**: sampling temperature (0.0-2.0)
- 📏 **Max Tokens**: Response length limit (passed directly to the LLM API to control the maximum length of the response) - **Max Tokens**: response length cap, passed to the LLM API
- ⏱️ **Request Interval**: API call throttling - **Request Interval**: minimum delay between API calls (seconds)
- 💾 **History Size**: Number of messages to retain - **History Size**: number of conversations to retain
- 🌍 **Custom API Endpoint**: Optional advanced configuration - **Custom API Endpoint**: for OpenRouter, proxies and self-hosted servers
- **Disable Thinking**: turn off model reasoning where the provider supports it
- **Allow Local Network**: permit endpoints on private addresses (needed for local servers like Ollama)
### 🤖 **Recommended Models** ### Recommended Models
#### OpenAI Models #### OpenAI Models
- **GPT-5** - The latest flagship model, best for complex reasoning - **GPT-5.6 Sol** - flagship tier for the hardest tasks
- **GPT-5 mini** - A cost-effective and fast model, suitable for most tasks - **GPT-5.6 Terra** - mid-tier for high-volume tasks
- **GPT-5.6 Luna** - fastest and cheapest, enough for most home automation queries
#### Anthropic Claude Models #### Anthropic Claude Models
- **Claude Opus 4.6** - The most capable model for handling complex tasks - **Claude Fable 5** - the most capable model for complex tasks
- **Claude Sonnet 4.6** - Offers a balance between performance and cost - **Claude Sonnet 5** - balance between quality and cost
- **Claude Haiku 4.5** - The fastest and most economical option in the series - **Claude Haiku 4.5** - the fastest and cheapest option in the lineup
#### DeepSeek Models #### DeepSeek Models
- **deepseek-v4-flash** - A fast general-purpose model for a wide range of tasks (default) - **deepseek-v4-flash** - fast general-purpose model (default)
- **deepseek-v4-pro** - A more capable model for reasoning and coding - **deepseek-v4-pro** - stronger at reasoning and coding
> The legacy model names `deepseek-chat` and `deepseek-reasoner` stop working on 2026-07-24. If your instance still uses one of them, switch the model in the integration options. > The legacy model names `deepseek-chat` and `deepseek-reasoner` stop working on 2026-07-24. If your instance still uses one of them, switch the model in the integration options.
#### Google Gemini Models #### Google Gemini Models
- **gemini-3.5-flash** - Fast and cost-efficient, suitable for most tasks (default) - **gemini-3.5-flash** - default; Google's strongest currently available model
- **Gemini 3.1 Pro** - The most advanced Gemini model available - **gemini-3.1-pro** - previous flagship, still supported
> Google shut down `gemini-2.0-flash` on 2026-06-01 and retires the 2.5 family on 2026-10-16. If your instance uses one of those, switch the model in the integration options. > Google shut down `gemini-2.0-flash` on 2026-06-01 and retires the 2.5 family on 2026-10-16. If your instance uses one of those, switch the model in the integration options.
<details> <details>
<summary>🌐 Potentially Compatible Providers</summary> <summary>Potentially Compatible Providers</summary>
#### Flexible Provider Ecosystem Other providers with OpenAI-compatible APIs may work through the custom endpoint option:
The integration is designed to be flexible and may work with other providers offering OpenAI-compatible APIs:
- Groq - Groq
- Together AI - Together AI
- Perplexity AI - Perplexity AI
- Mistral AI - Mistral AI
- Google AI - Local AI servers (like Ollama - enable **Allow Local Network** in the options)
- Local AI servers (like Ollama)
- Custom OpenAI-compatible endpoints - Custom OpenAI-compatible endpoints
#### 🚨 Compatibility Notes Compatibility is not guaranteed. A provider needs an OpenAI-like REST API with JSON request/response format, standard bearer authentication and similar parameter handling. Check the provider's documentation and make sure your API key has sufficient quota.
- Not all providers guarantee full compatibility
- Performance may vary between providers
- Check individual provider's documentation
- Ensure your API key has sufficient credits/quota
#### 🔍 Provider Compatibility Requirements
To be compatible, a provider should support:
- OpenAI-like REST API structure
- JSON request/response format
- Standard authentication method
- Similar model parameter handling
</details> </details>
## ⚡ Installation ## Installation
### HACS Installation (Recommended) ### HACS Installation (Recommended)
>[!TIP] >[!TIP]
@@ -189,10 +120,9 @@ To be compatible, a provider should support:
<a href="https://my.home-assistant.io/redirect/hacs_repository/?owner=smkrv&repository=ha-text-ai&category=Integration"><img src="https://my.home-assistant.io/badges/hacs_repository.svg" width="170" height="auto"></a> <a href="https://my.home-assistant.io/redirect/hacs_repository/?owner=smkrv&repository=ha-text-ai&category=Integration"><img src="https://my.home-assistant.io/badges/hacs_repository.svg" width="170" height="auto"></a>
1. Open HACS in Home Assistant 1. Open HACS in Home Assistant
2. Click on "Integrations" 2. Search for "HA Text AI"
3. Search for "HA Text AI" 3. Click "Download"
4. Click "Download" 4. Restart Home Assistant
5. Restart Home Assistant
**Alternative Method (Custom Repository):** **Alternative Method (Custom Repository):**
If the integration is not found in the default repository: If the integration is not found in the default repository:
@@ -206,57 +136,64 @@ If the integration is not found in the default repository:
1. Download `ha_text_ai.zip` from the latest release 1. Download `ha_text_ai.zip` from the latest release
2. Extract the archive and copy the `ha_text_ai` folder into your `custom_components` directory 2. Extract the archive and copy the `ha_text_ai` folder into your `custom_components` directory
3. Restart Home Assistant 3. Restart Home Assistant
4. Add configuration via UI (Settings → Devices & Services → Add Integration) 4. Add configuration via UI (Settings > Devices & Services > Add Integration)
## ⚙️ Configuration ## Configuration
### Via UI (Recommended) ### Via UI (Recommended)
1. Go to Settings → Devices & Services 1. Go to Settings > Devices & Services
2. Click "Add Integration" 2. Click "Add Integration"
3. Search for "HA Text AI" 3. Search for "HA Text AI"
4. Follow the configuration steps 4. Follow the configuration steps
> **Note:** This integration is configured exclusively through the UI (config entries). YAML configuration is not supported. > **Note:** This integration is configured exclusively through the UI (config entries). YAML configuration is not supported.
## 🛠️ Available Services ## Available Services
### 🔄 Response Variables (New!) ### Response Variables
**HA Text AI now supports response variables** - a powerful feature that returns AI responses directly from service calls, eliminating the need for separate text sensors and the 255-character limitation! `ask_question` returns its result directly to the calling automation via `response_variable`. The full response text comes back regardless of length (no 255-character truncation), it is available immediately without polling sensor state, and each service call gets its own result, so parallel automations don't overwrite each other.
#### ✨ Key Benefits:
- **Unlimited response length** - No more 255-character truncation
- **Direct data access** - Get responses immediately in automations
- **Race condition prevention** - Eliminates conflicts in parallel automations
- **Simplified workflows** - No need to read from sensors
### ask_question ### ask_question
```yaml ```yaml
service: ha_text_ai.ask_question service: ha_text_ai.ask_question
data: data:
question: "What's the optimal temperature for sleeping?" question: "What's the optimal temperature for sleeping?"
model: "claude-sonnet-4-6-20260217" # optional instance: sensor.ha_text_ai_claude
model: "claude-sonnet-5" # optional, overrides the configured model
temperature: 0.5 # optional temperature: 0.5 # optional
max_tokens: 500 # optional max_tokens: 500 # optional
context_messages: 10 #optional, number of previous messages to include in context, default: 5 context_messages: 10 # optional, previous messages to include (1-20, default 5)
system_prompt: "You are a sleep optimization expert" # optional system_prompt: "You are a sleep optimization expert" # optional
instance: sensor.ha_text_ai_gpt disable_thinking: true # optional, disable model reasoning for this request
response_variable: ai_response # NEW! Store response data directly response_variable: ai_response
``` ```
#### 📊 Response Data Structure: For structured JSON output, add `structured_output` with a schema:
```yaml
service: ha_text_ai.ask_question
data:
question: "Suggest three energy-saving actions for tonight"
instance: sensor.ha_text_ai_gpt
structured_output: true
json_schema: >-
{"type": "object", "properties": {"actions": {"type": "array", "items": {"type": "string"}}}}
response_variable: ai_response
```
#### Response Data Structure
```yaml ```yaml
# The service returns structured data: # The service returns structured data:
response_text: "The optimal sleeping temperature is 65-68°F (18-20°C)..." response_text: "The optimal sleeping temperature is 65-68°F (18-20°C)..."
tokens_used: 150 tokens_used: 150
prompt_tokens: 50 prompt_tokens: 50
completion_tokens: 100 completion_tokens: 100
model_used: "claude-sonnet-4-6-20260217" model_used: "claude-sonnet-5"
instance: "sensor.ha_text_ai_gpt" instance: "sensor.ha_text_ai_claude"
question: "What's the optimal temperature for sleeping?" question: "What's the optimal temperature for sleeping?"
timestamp: "2025-02-09T16:57:00.000Z" timestamp: "2026-07-09T16:57:00.000Z"
success: true success: true
# error: "Error message" (only present if success: false) # error and error_type are present only when success is false
``` ```
### set_system_prompt ### set_system_prompt
@@ -285,14 +222,14 @@ service: ha_text_ai.get_history
data: data:
limit: 5 # optional, number of conversations to return (values above 200 are clamped); omit to get the full stored history limit: 5 # optional, number of conversations to return (values above 200 are clamped); omit to get the full stored history
filter_model: "gpt-4o" # optional, filter by specific AI model filter_model: "gpt-4o" # optional, filter by specific AI model
start_date: "2025-02-01" # optional, filter conversations from this date start_date: "2026-02-01" # optional, filter conversations from this date
include_metadata: false # optional, include tokens, response time, etc. include_metadata: false # optional, include tokens, response time, etc.
sort_order: "newest" # optional, sort order: "newest" or "oldest" sort_order: "newest" # optional, sort order: "newest" or "oldest"
instance: sensor.ha_text_ai_gpt instance: sensor.ha_text_ai_gpt
response_variable: history_result # entries are in history_result.history response_variable: history_result # entries are in history_result.history
``` ```
## 🚀 Advanced Automation Examples with Response Variables ## Automation Examples with Response Variables
### Example 1: Smart Home Advice with Direct Response ### Example 1: Smart Home Advice with Direct Response
```yaml ```yaml
@@ -309,12 +246,12 @@ automation:
response_variable: ai_advice response_variable: ai_advice
- service: notify.mobile_app - service: notify.mobile_app
data: data:
title: "🏠 Smart Home Tip" title: "Smart Home Tip"
message: | message: |
{{ ai_advice.response_text }} {{ ai_advice.response_text }}
📊 Tokens used: {{ ai_advice.tokens_used }} Tokens used: {{ ai_advice.tokens_used }}
🤖 Model: {{ ai_advice.model_used }} Model: {{ ai_advice.model_used }}
``` ```
### Example 2: Weather-Based AI Recommendations ### Example 2: Weather-Based AI Recommendations
@@ -340,7 +277,7 @@ automation:
then: then:
- service: persistent_notification.create - service: persistent_notification.create
data: data:
title: "❄️ Winter Preparation Advice" title: "Winter Preparation Advice"
message: | message: |
{{ winter_advice.response_text }} {{ winter_advice.response_text }}
@@ -348,7 +285,7 @@ automation:
else: else:
- service: persistent_notification.create - service: persistent_notification.create
data: data:
title: "⚠️ AI Service Error" title: "AI Service Error"
message: "Failed to get winter advice: {{ winter_advice.error }}" message: "Failed to get winter advice: {{ winter_advice.error }}"
``` ```
@@ -384,10 +321,10 @@ automation:
instance: sensor.ha_text_ai_gpt instance: sensor.ha_text_ai_gpt
response_variable: recommendations response_variable: recommendations
# Step 3: Send comprehensive report # Step 3: Send the combined report
- service: notify.telegram - service: notify.telegram
data: data:
title: "🏠 Home Analysis Report" title: "Home Analysis Report"
message: | message: |
**Analysis:** **Analysis:**
{{ status_analysis.response_text }} {{ status_analysis.response_text }}
@@ -401,11 +338,11 @@ automation:
- Generated: {{ recommendations.timestamp }} - Generated: {{ recommendations.timestamp }}
``` ```
### 💡 Migration from Sensors to Response Variables ### Migration from Sensors to Response Variables
#### Old Method (Limited): #### Old Method:
```yaml ```yaml
# ❌ Old way - limited to 255 characters, race conditions # Old way: delay-based polling, response truncated by the 255-character state limit
automation: automation:
- alias: "Old AI Response Method" - alias: "Old AI Response Method"
action: action:
@@ -416,12 +353,12 @@ automation:
- delay: "00:00:05" # Wait for sensor update - delay: "00:00:05" # Wait for sensor update
- service: notify.mobile - service: notify.mobile
data: data:
message: "{{ state_attr('sensor.ha_text_ai_gpt', 'response')[:255] }}..." # Truncated! message: "{{ state_attr('sensor.ha_text_ai_gpt', 'response')[:255] }}..." # Truncated
``` ```
#### New Method (Unlimited): #### New Method:
```yaml ```yaml
# ✅ New way - unlimited length, immediate access, no race conditions # New way: full response, available immediately
automation: automation:
- alias: "New AI Response Method" - alias: "New AI Response Method"
action: action:
@@ -429,24 +366,23 @@ automation:
data: data:
question: "Long question here..." question: "Long question here..."
instance: sensor.ha_text_ai_gpt instance: sensor.ha_text_ai_gpt
response_variable: ai_response # Direct access! response_variable: ai_response
- service: notify.mobile - service: notify.mobile
data: data:
message: "{{ ai_response.response_text }}" # Full response, no truncation! message: "{{ ai_response.response_text }}" # Full response, no truncation
``` ```
### 🏷️ HA Text AI Sensor Naming Convention ### HA Text AI Sensor Naming Convention
#### Character Restrictions #### Naming Rules
- Only lowercase letters (a-z) - Only lowercase letters (a-z), numbers (0-9) and underscore (_)
- Numbers (0-9) - The part after the `sensor.ha_text_ai_` prefix is limited to 50 characters
- Underscore (_) - No spaces; keep it descriptive but short
- Maximum length: 50 characters (including `ha_text_ai_`)
#### Sensor Name Structure #### Sensor Name Structure
```yaml ```yaml
# Always starts with 'sensor.ha_text_ai_' # Always starts with 'sensor.ha_text_ai_'
# You define only the part after the underscore # You define only the part after the prefix
sensor.ha_text_ai_YOUR_UNIQUE_SUFFIX sensor.ha_text_ai_YOUR_UNIQUE_SUFFIX
# Examples: # Examples:
@@ -477,107 +413,99 @@ automation:
{{ state_attr('sensor.ha_text_ai_gpt', 'response') }} {{ state_attr('sensor.ha_text_ai_gpt', 'response') }}
``` ```
### 💡 Naming Rules ### HA Text AI Sensor Attributes
- Prefix is always `sensor.ha_text_ai_`
- Add your unique identifier after the underscore
- Use lowercase
- No spaces allowed
- Keep it descriptive but concise
### 🔍 HA Text AI Sensor Attributes - **Model and provider**: current model, API provider, model used for the last response
- **System status**: processing, rate-limit and endpoint state
- **Performance metrics**: request success/failure counters and latency statistics
- **Token usage**: total, prompt and completion token counters as reported by the provider's API
- **Last interaction**: most recent question, response and timestamp
- **System health**: error counter, maintenance flag, uptime
- 🤖 **Model and Provider Information**: Tracking current AI model and service provider Attributes may be 0 or empty until the first request completes.
- 🚦 **System Status**: Real-time API and processing readiness
- 📊 **Performance Metrics**: Request success rates and response times
- 💬 **Conversation Tracking**: Token usage and interaction history are estimated using a heuristic method based on word count and specific word characteristics, which may differ from actual token usage.
- 🕒 **Last Interaction Details**: Recent query and response tracking
- ❤️ **System Health**: Error monitoring and service uptime
<details> <details>
<summary>📦 Detailed Sensor Attributes</summary> <summary>Detailed Sensor Attributes</summary>
#### Model and Provider Information #### Model and Provider Information
```yaml ```yaml
# Name of the AI model currently in use (e.g., latest version of GPT) # Model currently configured for this instance
{{ state_attr('sensor.ha_text_ai_gpt', 'Model') }} # gpt-4o {{ state_attr('sensor.ha_text_ai_gpt', 'model') }} # gpt-4o-mini
# Service provider for the AI model (determines API endpoint and authentication) # Service provider (determines API endpoint and authentication)
{{ state_attr('sensor.ha_text_ai_gpt', 'Api provider') }} # openai {{ state_attr('sensor.ha_text_ai_gpt', 'api_provider') }} # openai
# Previous or alternative model configuration # Model that produced the last response (may differ after a per-request override)
{{ state_attr('sensor.ha_text_ai_gpt', 'Last model') }} # gpt-4o {{ state_attr('sensor.ha_text_ai_gpt', 'last_model') }} # gpt-4o-mini
``` ```
#### System Status #### System Status
```yaml ```yaml
# Indicates if a request is currently being processed # Indicates if a request is currently being processed
{{ state_attr('sensor.ha_text_ai_gpt', 'Is processing') }} # false {{ state_attr('sensor.ha_text_ai_gpt', 'is_processing') }} # false
# Shows if the API has hit its request rate limit # Shows if the API has hit its request rate limit
{{ state_attr('sensor.ha_text_ai_gpt', 'Is rate limited') }} # false {{ state_attr('sensor.ha_text_ai_gpt', 'is_rate_limited') }} # false
# Status of the specific API endpoint being used # Status of the API endpoint being used
{{ state_attr('sensor.ha_text_ai_gpt', 'Endpoint status') }} # ready {{ state_attr('sensor.ha_text_ai_gpt', 'endpoint_status') }} # ready
``` ```
#### Performance Metrics #### Performance Metrics
```yaml ```yaml
# Total number of successfully completed API requests # Number of successfully completed API requests
{{ state_attr('sensor.ha_text_ai_gpt', 'Successful requests') }} # 0 {{ state_attr('sensor.ha_text_ai_gpt', 'successful_requests') }} # 42
# Number of API requests that encountered errors # Number of API requests that encountered errors
{{ state_attr('sensor.ha_text_ai_gpt', 'Failed requests') }} # 0 {{ state_attr('sensor.ha_text_ai_gpt', 'failed_requests') }} # 0
# Mean time taken to receive a response from the AI service # Average / max / min response time, in seconds
{{ state_attr('sensor.ha_text_ai_gpt', 'Average latency') }} # 0 {{ state_attr('sensor.ha_text_ai_gpt', 'average_latency') }} # 1.85
{{ state_attr('sensor.ha_text_ai_gpt', 'max_latency') }} # 4.2
# Maximum time taken for a single request-response cycle {{ state_attr('sensor.ha_text_ai_gpt', 'min_latency') }} # 0.9
{{ state_attr('sensor.ha_text_ai_gpt', 'Max latency') }} # 0
``` ```
#### Conversation and Token Usage #### Conversation and Token Usage
```yaml ```yaml
# Number of previous interactions stored in conversation context # Number of entries in the current history file
{{ state_attr('sensor.ha_text_ai_gpt', 'History size') }} # 0 {{ state_attr('sensor.ha_text_ai_gpt', 'history_size') }} # 12
# Total number of tokens used across all interactions # Token counters as reported by the provider's API
{{ state_attr('sensor.ha_text_ai_gpt', 'Total tokens') }} # 0 {{ state_attr('sensor.ha_text_ai_gpt', 'total_tokens') }} # 4520
{{ state_attr('sensor.ha_text_ai_gpt', 'prompt_tokens') }} # 3100
{{ state_attr('sensor.ha_text_ai_gpt', 'completion_tokens') }} # 1420
# Tokens used in the input prompts # Last 3 conversation entries, each truncated to 256 characters
{{ state_attr('sensor.ha_text_ai_gpt', 'Prompt tokens') }} # 0 # (full history is available via the get_history service)
{{ state_attr('sensor.ha_text_ai_gpt', 'conversation_history') }} # [...]
# Tokens used in the AI's generated responses
{{ state_attr('sensor.ha_text_ai_gpt', 'Completion tokens') }} # 0
# Number of entries in current history file
{{ state_attr('sensor.ha_text_ai_gpt', 'History size') }} # 0
# Last few conversation entries (last 5 for performance)
{{ state_attr('sensor.ha_text_ai_gpt', 'conversation_history') }} # [...]
``` ```
#### Last Interaction Details #### Last Interaction Details
```yaml ```yaml
# Most recent complete response generated by the AI service # Most recent response, truncated to 2048 characters in the attribute
{{ state_attr('sensor.ha_text_ai_gpt', 'Response') }} # Last AI response # (the response_variable path returns the full text)
{{ state_attr('sensor.ha_text_ai_gpt', 'response') }} # Last AI response
# The most recently processed user query or prompt # The most recently processed question
{{ state_attr('sensor.ha_text_ai_gpt', 'Question') }} # Last asked question {{ state_attr('sensor.ha_text_ai_gpt', 'question') }} # Last asked question
# Precise moment when the last interaction occurred (useful for tracking and logging) # When the last interaction occurred
{{ state_attr('sensor.ha_text_ai_gpt', 'Last timestamp') }} # Timestamp {{ state_attr('sensor.ha_text_ai_gpt', 'last_timestamp') }} # Timestamp
``` ```
#### System Health #### System Health
```yaml ```yaml
# Cumulative count of all errors encountered during AI service interactions # Cumulative count of errors across all requests
{{ state_attr('sensor.ha_text_ai_gpt', 'Total errors') }} # 0 {{ state_attr('sensor.ha_text_ai_gpt', 'total_errors') }} # 0
# Indicates if the AI service is currently undergoing scheduled or emergency maintenance # Error message of the last failed request (null after a success)
{{ state_attr('sensor.ha_text_ai_gpt', 'Is maintenance') }} # false {{ state_attr('sensor.ha_text_ai_gpt', 'last_error') }} # null
# Total continuous operational time of the AI service (in hours or days) # Maintenance flag
{{ state_attr('sensor.ha_text_ai_gpt', 'Uptime') }} # 547,58 {{ state_attr('sensor.ha_text_ai_gpt', 'is_maintenance') }} # false
# Seconds since the integration instance was set up
{{ state_attr('sensor.ha_text_ai_gpt', 'uptime') }} # 547.58
``` ```
### History Storage ### History Storage
@@ -587,41 +515,36 @@ Conversation history stored in `.storage/ha_text_ai_history/` directory:
- Archived history files are timestamped - Archived history files are timestamped
- Default maximum file size: 1MB - Default maximum file size: 1MB
### 💡 Pro Tips
- Always check attribute existence
- Use these attributes for monitoring and automation
- Some values might be 0 or empty initially
</details> </details>
## 📘 FAQ ## FAQ
**Q: Which AI providers are supported?** **Q: Which AI providers are supported?**
A: OpenAI (GPT models), Anthropic (Claude models), DeepSeek, Google Gemini, and OpenRouter are officially supported, with many other OpenAI-compatible providers working as well. A: OpenAI, Anthropic, DeepSeek and Google Gemini are built-in providers. OpenRouter and other OpenAI-compatible services work through the OpenAI provider with a custom endpoint.
**Q: How can I reduce API costs?** **Q: How can I reduce API costs?**
A: Use gpt-5-mini or claude-haiku-4-5 for most queries, implement caching, and optimize token usage. A: Use a cheap fast model (GPT-5.6 Luna, Claude Haiku 4.5, deepseek-v4-flash, gemini-3.5-flash) for routine queries, lower `context_messages`, and cap `max_tokens`.
**Q: Are there limitations on the number of requests?** **Q: Are there limitations on the number of requests?**
A: Depends on your API provider's plan. We recommend monitoring usage and implementing request throttling via `request_interval` configuration. A: Depends on your API provider's plan. Monitor usage via the sensor attributes and throttle calls with the `request_interval` option.
**Q: Can I use custom models?** **Q: Can I use custom models?**
A: Yes, you can configure custom endpoints and use any compatible model by specifying it in the configuration. A: Yes, you can configure custom endpoints and use any compatible model by specifying it in the configuration.
**Q: How do I switch between different AI providers?** **Q: How do I switch between different AI providers?**
A: Simply change the model parameter in your configuration or service calls to use the desired provider's model. A: Each integration instance is bound to one provider. Add a separate instance per provider and pick the instance in your service calls; within an instance you can override the model per request.
**Q: What are the token limits for different models?** **Q: What are the token limits for different models?**
A: Token limits vary by provider and model. OpenAI's GPT-5 supports up to 1M context tokens, Claude Opus 4.6 supports up to 1M tokens, Gemini 3.1 Pro supports up to 1M tokens, while smaller models typically have 128K-200K limits. Check your provider's documentation for specific limits. A: Context window sizes vary by provider and model - check your provider's documentation. The `max_tokens` option caps only the response length, not the context window.
**Q: How do I monitor token usage?** **Q: How do I monitor token usage?**
A: Use the sensor attributes like `Total tokens`, `Prompt tokens`, and `Completion tokens` to track usage. You can also create automations to alert you when usage exceeds certain thresholds. A: Use the sensor attributes `total_tokens`, `prompt_tokens` and `completion_tokens`. You can also create automations to alert you when usage exceeds a threshold.
**Q: Is my data secure?** **Q: Is my data secure?**
A: Yes, your data is secure. The system operates entirely on your local machine, keeping your data under your control. API keys are stored securely and all external communications use encrypted connections. A: Conversation history and API keys are stored locally in your Home Assistant instance. Questions and context are sent to the provider you configure over HTTPS; nothing is shared with third parties beyond that provider.
**Q: How do context messages work?** **Q: How do context messages work?**
A: Context messages allow the AI to remember and reference previous conversation history. By default, 5 previous messages are included, but you can customize this from 1 to 20 messages to control the conversation depth and token usage. A: Context messages let the AI reference previous conversation history. By default 5 previous messages are included; you can set 1 to 20 per request to balance conversation depth against token usage.
**Q: Where is conversation history stored?** **Q: Where is conversation history stored?**
A: History is stored in files under the `.storage/ha_text_ai_history/` directory, with automatic rotation and size management. A: History is stored in files under the `.storage/ha_text_ai_history/` directory, with automatic rotation and size management.
@@ -630,9 +553,9 @@ A: History is stored in files under the `.storage/ha_text_ai_history/` directory
A: Yes, archived history files are stored with timestamps and can be accessed manually if needed. A: Yes, archived history files are stored with timestamps and can be accessed manually if needed.
**Q: How much history is kept?** **Q: How much history is kept?**
A: By default, up to 50 conversations are stored (max 200), configurable via UI. Files are automatically rotated when they reach 1MB. A: 50 conversations by default, configurable up to 100 in the UI. Files are automatically rotated when they reach 1MB.
## 🤝 Contributing ## Contributing
Contributions welcome! Please read our [Contributing Guide](CONTRIBUTING.md). Contributions welcome! Please read our [Contributing Guide](CONTRIBUTING.md).
@@ -655,12 +578,12 @@ DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN THE SOFTWARE. DEALINGS IN THE SOFTWARE.
## 📝 License ## License
Author: SMKRV Author: SMKRV
[MIT License](https://opensource.org/licenses/MIT) - see [LICENSE](LICENSE) for details. [MIT License](https://opensource.org/licenses/MIT) - see [LICENSE](LICENSE) for details.
## 💡 Support the Project ## Support the Project
The best support is: The best support is:
- Sharing feedback - Sharing feedback
@@ -674,16 +597,13 @@ If you want to say thanks financially, you can send a small token of appreciatio
**USDT Wallet (TRC10/TRC20):** **USDT Wallet (TRC10/TRC20):**
`TXC9zYHYPfWUGi4Sv4R1ctTBGScXXQk5HZ` `TXC9zYHYPfWUGi4Sv4R1ctTBGScXXQk5HZ`
*Open-source is built by community passion!* 🚀
--- ---
<div align="center"><img src="https://github.com/smkrv/ha-text-ai/blob/2aaf3405759eb2d97624834594e24ace896131df/assets/images/icons/footer_icon.png" alt="HA Text AI" style="width: 128px; height: auto;"/></div> <div align="center"><img src="https://github.com/smkrv/ha-text-ai/blob/2aaf3405759eb2d97624834594e24ace896131df/assets/images/icons/footer_icon.png" alt="HA Text AI" style="width: 128px; height: auto;"/></div>
<div align="center"> <div align="center">
Made with ❤️ for the Home Assistant Community Made for the Home Assistant Community
[Report Bug](https://github.com/smkrv/ha-text-ai/issues) · [Request Feature](https://github.com/smkrv/ha-text-ai/issues) [Report Bug](https://github.com/smkrv/ha-text-ai/issues) · [Request Feature](https://github.com/smkrv/ha-text-ai/issues)
</div> </div>