|
|
|
@@ -2,11 +2,11 @@
|
|
|
|
|
|
|
|
|
|
<div align="center">
|
|
|
|
|
|
|
|
|
|
  [](https://creativecommons.org/licenses/by-nc-sa/4.0/) [](https://github.com/hacs/integration)
|
|
|
|
|
  [](https://creativecommons.org/licenses/by-nc-sa/4.0/) [](https://github.com/hacs/integration)
|
|
|
|
|
       
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<img src="https://github.com/smkrv/ha-text-ai/blob/15c717fcb0204bf4a0d4b4b4c6f0bb93e9f6c9a9/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
|
|
|
|
|
</div>
|
|
|
|
@@ -106,7 +106,7 @@ Transform your smart home experience with powerful AI assistance powered by mult
|
|
|
|
|
|
|
|
|
|
## 📋 Prerequisites
|
|
|
|
|
|
|
|
|
|
- Home Assistant 2024.2.2 or later
|
|
|
|
|
- Home Assistant 2024.12.0 or later (recommended for best compatibility)
|
|
|
|
|
- Active API key from:
|
|
|
|
|
- OpenAI ([Get key](https://platform.openai.com/account/api-keys))
|
|
|
|
|
- Anthropic ([Get key](https://console.anthropic.com/))
|
|
|
|
@@ -120,7 +120,7 @@ Transform your smart home experience with powerful AI assistance powered by mult
|
|
|
|
|
## Configuration Options
|
|
|
|
|
|
|
|
|
|
### 🔧 **Core Configuration Settings**
|
|
|
|
|
- 🌐 **API Provider**: OpenAI/Anthropic/DeepSeek
|
|
|
|
|
- 🌐 **API Provider**: OpenAI/Anthropic/DeepSeek/Gemini
|
|
|
|
|
- 🔑 **API Key**: Provider-specific authentication
|
|
|
|
|
- 🤖 **Model Selection**: Flexible, provider-specific models
|
|
|
|
|
- 🌡️ **Temperature**: Creativity control (0.0-2.0)
|
|
|
|
@@ -129,6 +129,25 @@ Transform your smart home experience with powerful AI assistance powered by mult
|
|
|
|
|
- 💾 **History Size**: Number of messages to retain
|
|
|
|
|
- 🌍 **Custom API Endpoint**: Optional advanced configuration
|
|
|
|
|
|
|
|
|
|
### 🤖 **Recommended Models**
|
|
|
|
|
|
|
|
|
|
#### OpenAI Models
|
|
|
|
|
- **GPT-5** - The latest flagship model, best for complex reasoning
|
|
|
|
|
- **GPT-5 mini** - A cost-effective and fast model, suitable for most tasks
|
|
|
|
|
|
|
|
|
|
#### Anthropic Claude Models
|
|
|
|
|
- **Claude Opus 4.1** - The most capable model for handling complex tasks
|
|
|
|
|
- **Claude Sonnet 4** - Offers a balance between performance and cost
|
|
|
|
|
- **Claude Haiku 4** - The fastest and most economical option in the series
|
|
|
|
|
|
|
|
|
|
#### DeepSeek Models
|
|
|
|
|
- **DeepSeek-V3.1** - A general-purpose model for a wide range of tasks
|
|
|
|
|
- **DeepSeek-R1** - A specialized model focused on reasoning and coding
|
|
|
|
|
|
|
|
|
|
#### Google Gemini Models
|
|
|
|
|
- **Gemini 2.5 Pro & 2.5 Flash** - The newest and most advanced models available
|
|
|
|
|
- **Gemini 2.0 Pro & 2.0 Flash** - Previous generation models that are still powerful and efficient
|
|
|
|
|
|
|
|
|
|
<details>
|
|
|
|
|
<summary>🌐 Potentially Compatible Providers</summary>
|
|
|
|
|
|
|
|
|
@@ -166,12 +185,17 @@ 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>
|
|
|
|
|
1. Open HACS in Home Assistant
|
|
|
|
|
2. Click on "Integrations"
|
|
|
|
|
3. Click "..." in top right corner
|
|
|
|
|
4. Select "Custom repositories"
|
|
|
|
|
5. Add repository URL: `https://github.com/smkrv/ha-text-ai`
|
|
|
|
|
6. Choose "Integration" as category
|
|
|
|
|
7. Click "Download"
|
|
|
|
|
8. Restart Home Assistant
|
|
|
|
|
3. Search for "HA Text AI"
|
|
|
|
|
4. Click "Download"
|
|
|
|
|
5. 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 the latest release
|
|
|
|
@@ -196,7 +220,7 @@ To be compatible, a provider should support:
|
|
|
|
|
ha_text_ai:
|
|
|
|
|
api_provider: openai # Required
|
|
|
|
|
api_key: !secret ai_api_key # Required
|
|
|
|
|
model: gpt-4o-mini # Strongly recommended
|
|
|
|
|
model: gpt-4o # Strongly recommended
|
|
|
|
|
temperature: 0.7 # Optional
|
|
|
|
|
max_tokens: 1000 # Optional
|
|
|
|
|
request_interval: 1.0 # Optional
|
|
|
|
@@ -213,7 +237,7 @@ sensor:
|
|
|
|
|
- platform: ha_text_ai
|
|
|
|
|
name: "My AI Assistant" # Required, unique identifier
|
|
|
|
|
api_provider: openai # Optional (inherits from platform)
|
|
|
|
|
model: "gpt-4o-mini" # Optional
|
|
|
|
|
model: "gpt-4o" # Optional
|
|
|
|
|
temperature: 0.7 # Optional
|
|
|
|
|
max_tokens: 1000 # Optional
|
|
|
|
|
```
|
|
|
|
@@ -224,16 +248,16 @@ sensor:
|
|
|
|
|
|
|
|
|
|
| Parameter | Type | Required | Default | Description |
|
|
|
|
|
|-----------|------|----------|---------|-------------|
|
|
|
|
|
| `api_provider` | String | ✅ | - | AI service provider (openai, anthropic) |
|
|
|
|
|
| `api_provider` | String | ✅ | - | AI service provider (openai, anthropic, deepseek, gemini) |
|
|
|
|
|
| `api_key` | String | ✅ | - | Authentication key for AI service |
|
|
|
|
|
| `model` | String | ⚠️ | Provider default | Strongly recommended: Specific AI model to use. If not specified, the provider's default model will be used |
|
|
|
|
|
| `temperature` | Float | ❌ | 0.7 | Response creativity level (0.0-2.0) |
|
|
|
|
|
| `model` | String | ⚠️ | gpt-4o-mini | Strongly recommended: Specific AI model to use. Default varies by provider |
|
|
|
|
|
| `temperature` | Float | ❌ | 0.1 | Response creativity level (0.0-2.0) |
|
|
|
|
|
| `max_tokens` | Integer | ❌ | 1000 | Maximum response length |
|
|
|
|
|
| `request_interval` | Float | ❌ | 1.0 | Delay between API requests |
|
|
|
|
|
| `api_endpoint` | URL | ⚠️ | Provider default | Custom API endpoint |
|
|
|
|
|
| `system_prompt` | String | ❌ | - | Default context for AI interactions |
|
|
|
|
|
| `max_history_size` | Integer | ❌ | 100 | Maximum number of conversation entries to store |
|
|
|
|
|
| `history_file_size` | Integer | ⚠️ | 1 | Maximum history file size in MB |
|
|
|
|
|
| `max_history_size` | Integer | ❌ | 50 | Maximum number of conversation entries to store |
|
|
|
|
|
| `context_messages` | Integer | ❌ | 5 | Number of previous messages to include in context (1-20) |
|
|
|
|
|
|
|
|
|
|
#### Sensor Configuration
|
|
|
|
|
|
|
|
|
@@ -242,9 +266,9 @@ sensor:
|
|
|
|
|
| `platform` | String | ✅ | - | Must be `ha_text_ai` |
|
|
|
|
|
| `name` | String | ✅ | - | Unique sensor identifier |
|
|
|
|
|
| `api_provider` | String | ❌ | Platform setting | Override global provider |
|
|
|
|
|
| `model` | String | ⚠️ | Platform setting | Recommended: Override global model. If not specified, uses platform or provider default |
|
|
|
|
|
| `temperature` | Float | ❌ | Platform setting | Override global temperature |
|
|
|
|
|
| `max_tokens` | Integer | ❌ | Platform setting | Override global max tokens |
|
|
|
|
|
| `model` | String | ⚠️ | Provider default | Recommended: Override global model (gpt-4o-mini, deepseek-chat, gemini-2.0-flash) |
|
|
|
|
|
| `temperature` | Float | ❌ | 0.1 | Override global temperature |
|
|
|
|
|
| `max_tokens` | Integer | ❌ | 1000 | Override global max tokens |
|
|
|
|
|
|
|
|
|
|
</details>
|
|
|
|
|
|
|
|
|
@@ -265,7 +289,7 @@ sensor:
|
|
|
|
|
service: ha_text_ai.ask_question
|
|
|
|
|
data:
|
|
|
|
|
question: "What's the optimal temperature for sleeping?"
|
|
|
|
|
model: "claude-3-sonnet" # optional
|
|
|
|
|
model: "claude-3.5-sonnet" # optional
|
|
|
|
|
temperature: 0.5 # optional
|
|
|
|
|
max_tokens: 500 # optional
|
|
|
|
|
context_messages: 10 #optional, number of previous messages to include in context, default: 5
|
|
|
|
@@ -281,10 +305,10 @@ 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-3-sonnet"
|
|
|
|
|
model_used: "claude-3.5-sonnet"
|
|
|
|
|
instance: "sensor.ha_text_ai_gpt"
|
|
|
|
|
question: "What's the optimal temperature for sleeping?"
|
|
|
|
|
timestamp: "2025-01-09T16:57:00.000Z"
|
|
|
|
|
timestamp: "2025-02-09T16:57:00.000Z"
|
|
|
|
|
success: true
|
|
|
|
|
# error: "Error message" (only present if success: false)
|
|
|
|
|
```
|
|
|
|
@@ -313,8 +337,11 @@ data:
|
|
|
|
|
```yaml
|
|
|
|
|
service: ha_text_ai.get_history
|
|
|
|
|
data:
|
|
|
|
|
limit: 5 # optional
|
|
|
|
|
filter_model: "gpt-4o" # optional
|
|
|
|
|
limit: 5 # optional, number of conversations to return (1-100)
|
|
|
|
|
filter_model: "gpt-4o" # optional, filter by specific AI model
|
|
|
|
|
start_date: "2025-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
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
@@ -626,10 +653,10 @@ Conversation history stored in `.storage/ha_text_ai_history/` directory:
|
|
|
|
|
## 📘 FAQ
|
|
|
|
|
|
|
|
|
|
**Q: Which AI providers are supported?**
|
|
|
|
|
A: Currently OpenAI (GPT models) and Anthropic (Claude models) are supported, with more providers planned.
|
|
|
|
|
A: OpenAI (GPT models), Anthropic (Claude models), DeepSeek, Google Gemini, and OpenRouter are officially supported, with many other OpenAI-compatible providers working as well.
|
|
|
|
|
|
|
|
|
|
**Q: How can I reduce API costs?**
|
|
|
|
|
A: Use GPT-3.5-Turbo or Claude-3-Sonnet for most queries, implement caching, and optimize token usage.
|
|
|
|
|
A: Use gpt-4o-mini or claude-3.5-haiku for most queries, implement caching, and optimize token usage.
|
|
|
|
|
|
|
|
|
|
**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.
|
|
|
|
@@ -640,8 +667,11 @@ A: Yes, you can configure custom endpoints and use any compatible model by speci
|
|
|
|
|
**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.
|
|
|
|
|
|
|
|
|
|
**Q: How can I reduce API costs?**
|
|
|
|
|
A: Use GPT-3.5-Turbo for most queries, implement caching, and optimize token usage.
|
|
|
|
|
**Q: What are the token limits for different models?**
|
|
|
|
|
A: Token limits vary by provider and model. OpenAI's gpt-4o supports up to 128K tokens, Claude 3.5 Sonnet supports up to 200K tokens, while smaller models typically have 8K-32K limits. Check your provider's documentation for specific limits.
|
|
|
|
|
|
|
|
|
|
**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.
|
|
|
|
|
|
|
|
|
|
**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.
|
|
|
|
@@ -707,8 +737,7 @@ If you want to say thanks financially, you can send a small token of appreciatio
|
|
|
|
|
<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">
|
|
|
|
|
|
|
|
|
|
Made with ❤️ for the Home Assistant Community,
|
|
|
|
|
utilizing Claude 3.5 Sonnet, Gemini Pro 1.5, and Qwen 2.5 Coder 32B Instruct.
|
|
|
|
|
Made with ❤️ 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)
|
|
|
|
|
|
|
|
|
|
SMKRV
smkrvandGitHub
SMKRV