### Multi-provider LLM integration for [Home Assistant](https://www.home-assistant.io/)
### Multi-provider LLM integration for [Home Assistant](https://www.home-assistant.io/)
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.
--- > [!IMPORTANT] > 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)** > >
>
> [Screenshots](assets/images/screenshots/screenshot.jpg)
## Features
- **Multi-provider support**: OpenAI, Anthropic Claude, DeepSeek, Google Gemini, plus any OpenAI-compatible endpoint
- **Conversation context**: the model sees previous messages; depth is configurable per request (1-20)
- **Response variables**: `ask_question` returns the full response directly to the calling automation, bypassing the 255-character state limit
- **Structured output**: JSON responses matching a schema you provide
- **Per-request overrides**: model, temperature, max_tokens, system prompt, thinking mode
- **Usage metrics**: token counters, latency and success/error statistics as sensor attributes
- **File-based history**: per-instance JSON storage with automatic rotation at 1 MB
#### Translations
| Code | Language | Status |
|------|----------|--------|
| de | Deutsch | Full |
| en | English | Primary |
| es | Español | Full |
| hi | हिन्दी | Full |
| it | Italiano | Full |
| ru | Русский | Full |
| sr | Српски | Full |
| zh | 中文 | Full |
## Prerequisites
- Home Assistant 2024.12.0 or later
- An API key from one of:
- OpenAI ([Get key](https://platform.openai.com/account/api-keys))
- Anthropic ([Get key](https://console.anthropic.com/))
- DeepSeek ([Get key](https://platform.deepseek.com/api_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))
- Any OpenAI-compatible API provider
## Configuration Options
### Core Configuration Settings
- **API Provider**: OpenAI / Anthropic / DeepSeek / Gemini
- **API Key**: provider-specific authentication
- **Model**: any model your provider offers
- **Temperature**: sampling temperature (0.0-2.0)
- **Max Tokens**: response length cap, passed to the LLM API
- **Request Interval**: minimum delay between API calls (seconds)
- **History Size**: number of conversations to retain
- **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
#### OpenAI Models
- **GPT-5.6 Sol** - flagship tier for the hardest 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
- **Claude Fable 5** - the most capable model for complex tasks
- **Claude Sonnet 5** - balance between quality and cost
- **Claude Haiku 4.5** - the fastest and cheapest option in the lineup
#### DeepSeek Models
- **deepseek-v4-flash** - fast general-purpose model (default)
- **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.
#### Google Gemini Models
- **gemini-3.5-flash** - default; Google's strongest currently available model
- **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.
1. Open HACS in Home Assistant
2. Search for "HA Text AI"
3. Click "Download"
4. Restart Home Assistant
**Alternative Method (Custom Repository):**
If the integration is not found in the default repository:
1. Click "..." in top right corner of HACS
2. Select "Custom repositories"
3. Add repository URL: `https://github.com/smkrv/ha-text-ai`
4. Choose "Integration" as category
5. Click "Download"
### Manual Installation
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
3. Restart Home Assistant
4. Add configuration via UI (Settings > Devices & Services > Add Integration)
## Configuration
### Via UI (Recommended)
1. Go to Settings > Devices & Services
2. Click "Add Integration"
3. Search for "HA Text AI"
4. Follow the configuration steps
> **Note:** This integration is configured exclusively through the UI (config entries). YAML configuration is not supported.
## Available Services
### Response Variables
`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.
### ask_question
```yaml
service: ha_text_ai.ask_question
data:
question: "What's the optimal temperature for sleeping?"
instance: sensor.ha_text_ai_claude
model: "claude-sonnet-5" # optional, overrides the configured model
temperature: 0.5 # optional
max_tokens: 500 # optional
context_messages: 10 # optional, previous messages to include (1-20, default 5)
system_prompt: "You are a sleep optimization expert" # optional
disable_thinking: true # optional, disable model reasoning for this request
response_variable: ai_response
```
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
# The service returns structured data:
response_text: "The optimal sleeping temperature is 65-68°F (18-20°C)..."
tokens_used: 150
prompt_tokens: 50
completion_tokens: 100
model_used: "claude-sonnet-5"
instance: "sensor.ha_text_ai_claude"
question: "What's the optimal temperature for sleeping?"
timestamp: "2026-07-09T16:57:00.000Z"
success: true
# error and error_type are present only when success is false
```
### set_system_prompt
```yaml
service: ha_text_ai.set_system_prompt
data:
instance: sensor.ha_text_ai_gpt
prompt: |
You are a home automation expert focused on:
1. Energy efficiency
2. Comfort optimization
3. Security considerations
Provide practical, actionable advice.
```
### clear_history
```yaml
service: ha_text_ai.clear_history
data:
instance: sensor.ha_text_ai_gpt
```
### get_history
```yaml
service: ha_text_ai.get_history
data:
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
start_date: "2026-02-01" # optional, filter conversations from this date
include_metadata: false # optional, include tokens, response time, etc.
sort_order: "newest" # optional, sort order: "newest" or "oldest"
instance: sensor.ha_text_ai_gpt
response_variable: history_result # entries are in history_result.history
```
## Automation Examples with Response Variables
### Example 1: Smart Home Advice with Direct Response
```yaml
automation:
- alias: "Get AI Home Advice"
trigger:
- platform: state
entity_id: input_button.ask_ai_advice
action:
- service: ha_text_ai.ask_question
data:
question: "What's the best way to optimize energy usage in my home?"
instance: sensor.ha_text_ai_gpt
response_variable: ai_advice
- service: notify.mobile_app
data:
title: "Smart Home Tip"
message: |
{{ ai_advice.response_text }}
Tokens used: {{ ai_advice.tokens_used }}
Model: {{ ai_advice.model_used }}
```
### Example 2: Weather-Based AI Recommendations
```yaml
automation:
- alias: "Weather-Based AI Suggestions"
trigger:
- platform: numeric_state
entity_id: sensor.outdoor_temperature
below: 0
action:
- service: ha_text_ai.ask_question
data:
question: |
The outdoor temperature is {{ states('sensor.outdoor_temperature') }}°C.
What should I do to prepare my home for freezing weather?
system_prompt: "You are a home maintenance expert. Provide practical, actionable advice."
instance: sensor.ha_text_ai_gpt
response_variable: winter_advice
- if:
- condition: template
value_template: "{{ winter_advice.success }}"
then:
- service: persistent_notification.create
data:
title: "Winter Preparation Advice"
message: |
{{ winter_advice.response_text }}
Generated at: {{ winter_advice.timestamp }}
else:
- service: persistent_notification.create
data:
title: "AI Service Error"
message: "Failed to get winter advice: {{ winter_advice.error }}"
```
### Example 3: Multi-Step AI Workflow
```yaml
automation:
- alias: "Multi-Step AI Analysis"
trigger:
- platform: state
entity_id: input_button.analyze_home_status
action:
# Step 1: Get current status analysis
- service: ha_text_ai.ask_question
data:
question: |
Current home status:
- Temperature: {{ states('sensor.indoor_temperature') }}°C
- Humidity: {{ states('sensor.indoor_humidity') }}%
- Energy usage: {{ states('sensor.power_consumption') }}W
Analyze this data and provide insights.
instance: sensor.ha_text_ai_gpt
response_variable: status_analysis
# Step 2: Get recommendations based on analysis
- service: ha_text_ai.ask_question
data:
question: |
Based on this analysis: "{{ status_analysis.response_text[:500] }}"
Provide 3 specific actionable recommendations for improvement.
context_messages: 2 # Include previous conversation
instance: sensor.ha_text_ai_gpt
response_variable: recommendations
# Step 3: Send the combined report
- service: notify.telegram
data:
title: "Home Analysis Report"
message: |
**Analysis:**
{{ status_analysis.response_text }}
**Recommendations:**
{{ recommendations.response_text }}
**Report Details:**
- Total tokens used: {{ status_analysis.tokens_used + recommendations.tokens_used }}
- Analysis model: {{ status_analysis.model_used }}
- Generated: {{ recommendations.timestamp }}
```
### Migration from Sensors to Response Variables
#### Old Method:
```yaml
# Old way: delay-based polling, response truncated by the 255-character state limit
automation:
- alias: "Old AI Response Method"
action:
- service: ha_text_ai.ask_question
data:
question: "Long question here..."
instance: sensor.ha_text_ai_gpt
- delay: "00:00:05" # Wait for sensor update
- service: notify.mobile
data:
message: "{{ state_attr('sensor.ha_text_ai_gpt', 'response')[:255] }}..." # Truncated
```
#### New Method:
```yaml
# New way: full response, available immediately
automation:
- alias: "New AI Response Method"
action:
- service: ha_text_ai.ask_question
data:
question: "Long question here..."
instance: sensor.ha_text_ai_gpt
response_variable: ai_response
- service: notify.mobile
data:
message: "{{ ai_response.response_text }}" # Full response, no truncation
```
### HA Text AI Sensor Naming Convention
#### Naming Rules
- Only lowercase letters (a-z), numbers (0-9) and underscore (_)
- The part after the `sensor.ha_text_ai_` prefix is limited to 50 characters
- No spaces; keep it descriptive but short
#### Sensor Name Structure
```yaml
# Always starts with 'sensor.ha_text_ai_'
# You define only the part after the prefix
sensor.ha_text_ai_YOUR_UNIQUE_SUFFIX
# Examples:
sensor.ha_text_ai_gpt # GPT-based sensor
sensor.ha_text_ai_claude # Claude-based sensor
sensor.ha_text_ai_abc # Custom suffix
```
#### Response Retrieval
```yaml
# Use your specific sensor name
{{ state_attr('sensor.ha_text_ai_gpt', 'response') }}
```
#### Practical Usage
```yaml
automation:
- alias: "AI Response with Custom Sensor"
action:
- service: ha_text_ai.ask_question
data:
question: "Home automation advice"
instance: sensor.ha_text_ai_gpt
- service: notify.mobile
data:
message: >
AI Tip:
{{ state_attr('sensor.ha_text_ai_gpt', 'response') }}
```
### 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
Attributes may be 0 or empty until the first request completes.
