mirror of
https://github.com/smkrv/ha-text-ai.git
synced 2026-07-23 07:33:58 +08:00
354 lines
11 KiB
Markdown
354 lines
11 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 compi
|
|
|
|
## 🌟 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 ❤️ 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>
|