mirror of
https://github.com/smkrv/ha-text-ai.git
synced 2026-07-22 07:03:58 +08:00
365 lines
12 KiB
Markdown
365 lines
12 KiB
Markdown
# 🤖 HA Text AI for Home Assistant
|
|
|
|
<div align="center">
|
|
|
|
    [](https://opensource.org/licenses/MIT) [](https://github.com/hacs/integration)
|
|
|
|
<img src="https://github.com/smkrv/ha-text-ai/blob/3e3ec45b195c92989434fde40ae110027f4ea124/misc/icons/icon.png" alt="HA Text AI" width="140"/>
|
|
|
|
### Advanced AI Integration for Home Assistant with multi-provider support
|
|
</div>
|
|
|
|
<p align="center">
|
|
Transform your smart home experience with powerful AI assistance powered by multiple AI providers including OpenAI GPT and Anthropic Claude models. Get intelligent responses, automate complex scenarios, and enhance your home automation with advanced natural language processing.
|
|
|
|
</p>
|
|
|
|
---
|
|
|
|
> [!IMPORTANT]
|
|
> 🚧 ALPHA VERSION 🚧
|
|
> Expect: potential bugs, frequent changes, incomplete features.
|
|
> 🤝 Community Driven
|
|
>
|
|
> <a href="https://community.home-assistant.io/t/ha-text-ai-transforming-home-automation-with-multi-provider-language-models/799741"><img src="https://img.shields.io/badge/Community-blue?style=for-the-badge&logo=homeassistant&logoColor=white&color=03a9f4"/></a>
|
|
|
|
## 🌟 Features
|
|
|
|
- 🧠 **Multi-Provider AI Integration**:
|
|
- Support for OpenAI GPT models
|
|
- Anthropic Claude 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**:
|
|
- Persistent conversation history
|
|
- Context-aware responses
|
|
- Customizable history limits
|
|
- Model-specific filtering
|
|
|
|
- ⚡ **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
|
|
|
|
## 📋 Prerequisites
|
|
|
|
- Home Assistant 2023.11 or later
|
|
- Active API key from:
|
|
- OpenAI ([Get key](https://platform.openai.com/account/api-keys))
|
|
- Anthropic ([Get key](https://console.anthropic.com/))
|
|
- OpenRouter ([Get key](https://openrouter.ai/keys))
|
|
- Python 3.9 or newer
|
|
- Stable internet connection
|
|
|
|
### Configuration Options
|
|
- API Provider (OpenAI/Anthropic)
|
|
- API Key (provider-specific)
|
|
- Model Selection (flexible, provider-specific models)
|
|
- Temperature (Creativity control, 0.0-2.0)
|
|
- Max Tokens (Response length limit)
|
|
- Request Interval (API call throttling)
|
|
- Custom API Endpoint (optional)
|
|
|
|
#### ⓘ Potentially Compatible Providers
|
|
The integration is designed to be flexible and may work with other providers offering OpenAI-compatible APIs:
|
|
- Groq
|
|
- Together AI
|
|
- Perplexity AI
|
|
- Mistral AI
|
|
- Google AI
|
|
- Local AI servers (like Ollama)
|
|
- Custom OpenAI-compatible endpoints
|
|
|
|
#### Additional Notes
|
|
- 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
|
|
|
|
## ⚡ Installation
|
|
|
|
### HACS Installation (Recommended)
|
|
<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
|
|
|
|
### Manual Installation
|
|
1. Download the latest release
|
|
2. Extract and copy `custom_components/ha_text_ai` to your `custom_components` directory
|
|
3. Restart Home Assistant
|
|
4. Add configuration via UI or YAML
|
|
|
|
## ⚙️ 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
|
|
|
|
### Via YAML
|
|
```yaml
|
|
ha_text_ai:
|
|
api_provider: openai # or anthropic
|
|
api_key: !secret ai_api_key
|
|
model: gpt-4o-mini
|
|
temperature: 0.7
|
|
max_tokens: 1000
|
|
request_interval: 1.0
|
|
api_endpoint: https://api.openai.com/v1 # optional, for custom endpoints
|
|
system_prompt: |
|
|
You are a home automation expert assistant.
|
|
Focus on practical and efficient solutions.
|
|
```
|
|
|
|
## 🛠️ Available Services
|
|
|
|
### ask_question
|
|
```yaml
|
|
service: ha_text_ai.ask_question
|
|
data:
|
|
question: "What's the optimal temperature for sleeping?"
|
|
model: "claude-3-sonnet" # optional
|
|
temperature: 0.5 # optional
|
|
max_tokens: 500 # optional
|
|
context_messages: 10 #optional, number of previous messages to include in context, default: 5
|
|
system_prompt: "You are a sleep optimization expert" # optional
|
|
```
|
|
|
|
### set_system_prompt
|
|
```yaml
|
|
service: ha_text_ai.set_system_prompt
|
|
data:
|
|
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
|
|
```
|
|
|
|
### get_history
|
|
```yaml
|
|
service: ha_text_ai.get_history
|
|
data:
|
|
limit: 5 # optional
|
|
filter_model: "gpt-4o" # optional
|
|
```
|
|
|
|
### 🏷️ HA Text AI Sensor Naming Convention
|
|
|
|
#### Sensor Name Structure
|
|
```yaml
|
|
# Always starts with 'sensor.ha_text_ai_'
|
|
# You define only the part after the underscore
|
|
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_gpt # 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"
|
|
- service: notify.mobile
|
|
data:
|
|
message: >
|
|
AI Tip:
|
|
{{ state_attr('sensor.ha_text_ai_gpt', 'response') }}
|
|
```
|
|
|
|
### 💡 Naming Rules
|
|
- 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 Information
|
|
```yaml
|
|
# Model details
|
|
{{ state_attr('sensor.ha_text_ai_gpt', 'Model') }} # gpt-4o
|
|
{{ state_attr('sensor.ha_text_ai_gpt', 'Api provider') }} # openai
|
|
{{ state_attr('sensor.ha_text_ai_gpt', 'Last model') }} # gpt-4o
|
|
```
|
|
|
|
#### System Status
|
|
```yaml
|
|
# Operational status
|
|
{{ state_attr('sensor.ha_text_ai_gpt', 'Api status') }} # ready
|
|
{{ state_attr('sensor.ha_text_ai_gpt', 'Is processing') }} # false
|
|
{{ state_attr('sensor.ha_text_ai_gpt', 'Is rate limited') }} # false
|
|
{{ state_attr('sensor.ha_text_ai_gpt', 'Endpoint status') }} # ready
|
|
```
|
|
|
|
#### Performance Metrics
|
|
```yaml
|
|
# Request and performance statistics
|
|
{{ state_attr('sensor.ha_text_ai_gpt', 'Successful requests') }} # 0
|
|
{{ state_attr('sensor.ha_text_ai_gpt', 'Failed requests') }} # 0
|
|
{{ state_attr('sensor.ha_text_ai_gpt', 'Average latency') }} # 0
|
|
{{ state_attr('sensor.ha_text_ai_gpt', 'Max latency') }} # 0
|
|
```
|
|
|
|
#### Conversation and Token Usage
|
|
```yaml
|
|
# Conversation and token details
|
|
{{ state_attr('sensor.ha_text_ai_gpt', 'History size') }} # 0
|
|
{{ state_attr('sensor.ha_text_ai_gpt', 'Total tokens') }} # 0
|
|
{{ state_attr('sensor.ha_text_ai_gpt', 'Prompt tokens') }} # 0
|
|
{{ state_attr('sensor.ha_text_ai_gpt', 'Completion tokens') }} # 0
|
|
```
|
|
|
|
#### Last Interaction Details
|
|
```yaml
|
|
# Last interaction information
|
|
{{ state_attr('sensor.ha_text_ai_gpt', 'Response') }} # Last AI response
|
|
{{ state_attr('sensor.ha_text_ai_gpt', 'Question') }} # Last asked question
|
|
{{ state_attr('sensor.ha_text_ai_gpt', 'Last timestamp') }} # Timestamp
|
|
```
|
|
|
|
#### System Health
|
|
```yaml
|
|
# System health and maintenance
|
|
{{ state_attr('sensor.ha_text_ai_gpt', 'Total errors') }} # 0
|
|
{{ state_attr('sensor.ha_text_ai_gpt', 'Is maintenance') }} # false
|
|
{{ state_attr('sensor.ha_text_ai_gpt', 'Uptime') }} # 547,58
|
|
```
|
|
|
|
### 💡 Pro Tips
|
|
- Always check attribute existence
|
|
- Use these attributes for monitoring and automation
|
|
- Some values might be 0 or empty initially
|
|
|
|
|
|
## 📘 FAQ
|
|
|
|
**Q: Which AI providers are supported?**
|
|
A: Currently OpenAI (GPT models) and Anthropic (Claude models) are supported, with more providers planned.
|
|
|
|
**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.
|
|
|
|
**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.
|
|
|
|
**Q: Can I use custom models?**
|
|
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?**
|
|
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: 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.
|
|
|
|
**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.
|
|
|
|
## 🤝 Contributing
|
|
|
|
Contributions welcome! Please read our [Contributing Guide](CONTRIBUTING.md).
|
|
|
|
1. Fork the repository
|
|
2. Create feature branch (`git checkout -b feature/Enhancement`)
|
|
3. Commit changes (`git commit -m 'Add Enhancement'`)
|
|
4. Push branch (`git push origin feature/Enhancement`)
|
|
5. Open Pull Request
|
|
|
|
## 📝 License
|
|
|
|
MIT License - see [LICENSE](LICENSE) for details.
|
|
|
|
## 💡 Support the Project
|
|
|
|
The best support is:
|
|
- Sharing feedback
|
|
- Contributing ideas
|
|
- Recommending to friends
|
|
- Reporting issues
|
|
- Star the repository
|
|
|
|
If you want to say thanks financially, you can send a small token of appreciation in USDT:
|
|
|
|
**USDT Wallet (TRC10/TRC20):**
|
|
`TXC9zYHYPfWUGi4Sv4R1ctTBGScXXQk5HZ`
|
|
|
|
*Open-source is built by community passion!* 🚀
|
|
|
|
---
|
|
|
|
<div align="center">
|
|
|
|
Made with ❤️ and Claude 3.5 Sonnet 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)
|
|
|
|
</div>
|