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

docs: update HACS installation for custom

Browse Source 
repository

  - Change HACS badge from Default to Custom
  - Add custom repository installation steps
  - Update installation instructions
  - Revise documentation format
This commit is contained in:
SMKRV
2024-11-19 19:03:51 +03:00
parent 9a7635c2ae
commit dc03faa97e
1 changed files with 64 additions and 127 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+64 -127
View File
@@ -1,73 +1,88 @@
```markdown
# 🤖 HA Text AI for Home Assistant # 🤖 HA Text AI for Home Assistant
<div align="center"> <div align="center">
![GitHub release](https://img.shields.io/github/release/smkrv/ha-text-ai.svg?style=flat-square) ![GitHub release](https://img.shields.io/github/release/smkrv/ha-text-ai.svg?style=flat-square)
![GitHub downloads](https://img.shields.io/github/downloads/smkrv/ha-text-ai/total.svg?style=flat-square) ![GitHub downloads](https://img.shields.io/github/downloads/smkrv/ha-text-ai/total.svg?style=flat-square)
![GitHub stars](https://img.shields.io/github/stars/smkrv/ha-text-ai.svg?style=social) ![GitHub stars](https://img.shields.io/github/stars/smkrv/ha-text-ai.svg?style=social)
![GitHub last commit](https://img.shields.io/github/last-commit/smkrv/ha-text-ai.svg?style=flat-square) ![GitHub last commit](https://img.shields.io/github/last-commit/smkrv/ha-text-ai.svg?style=flat-square)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
[![hacs_badge](https://img.shields.io/badge/HACS-Default-orange.svg?style=flat-square)](https://github.com/hacs/integration) [![hacs_badge](https://img.shields.io/badge/HACS-Custom-41BDF5.svg?style=flat-square)](https://github.com/hacs/integration)
[![Community Forum](https://img.shields.io/badge/Community-Forum-blue.svg?style=flat-square)](https://community.home-assistant.io/t/ha-text-ai-integration) [![Community Forum](https://img.shields.io/badge/Community-Forum-blue.svg?style=flat-square)](https://community.home-assistant.io/t/ha-text-ai-integration)
</div> </div>
<p align="center"> <p align="center">
Transform your smart home experience with powerful AI assistance powered by OpenAI's GPT models. Get intelligent responses, automate complex scenarios, and enhance your home automation with natural language processing. 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> </p>
--- ---
## 🌟 Features ## 🌟 Features
- 🧠 **Advanced AI Integration**: - 🧠 **Multi-Provider AI Integration**:
- Support for latest GPT models - Support for OpenAI GPT models
- Anthropic Claude integration
- Custom API endpoints
- Flexible model selection
- 💬 **Advanced Language Processing**:
- Context-aware responses - Context-aware responses
- Multi-turn conversations - Multi-turn conversations
- 💬 **Natural Language Control**: - Custom system instructions
- Control devices using everyday language
- Get detailed explanations and recommendations
- Natural conversation flow - Natural conversation flow
- 📝 **Smart Memory Management**: - 📝 **Enhanced Memory Management**:
- Persistent conversation history - Persistent conversation history
- Context-aware responses - Context-aware responses
- Customizable history limits - Customizable history limits
- ⚡ **Performance Optimized**: - Model-specific filtering
- ⚡ **Performance Optimization**:
- Efficient token usage - Efficient token usage
- Rate limit handling - Smart rate limiting
- Response caching - Response caching
- Request interval control
- 🎯 **Advanced Customization**: - 🎯 **Advanced Customization**:
- Adjustable response parameters - Per-request model selection
- Adjustable parameters
- Custom system prompts - Custom system prompts
- Model selection per request - Temperature control
- 🔒 **Enhanced Security**: - 🔒 **Enhanced Security**:
- Secure API key storage - Secure API key storage
- Rate limiting protection - Rate limiting protection
- Error handling - Error handling
- 🎨 **User Experience**: - Usage monitoring
- 🎨 **Improved User Experience**:
- Intuitive configuration UI - Intuitive configuration UI
- Detailed sensor attributes - Detailed sensor attributes
- Rich service interface - Rich service interface
- Model selection UI
- 🔄 **Automation Integration**: - 🔄 **Automation Integration**:
- Event-driven responses - Event-driven responses
- Conditional logic support - Conditional logic support
- Template compatibility - Template compatibility
- Model-specific automation
## 📋 Prerequisites ## 📋 Prerequisites
- Home Assistant 2023.8.0 or newer - Home Assistant 2023.8.0 or newer
- OpenAI API key ([Get one here](https://platform.openai.com/account/api-keys)) - API key from supported providers:
- OpenAI ([Get key](https://platform.openai.com/account/api-keys))
- Anthropic ([Get key](https://console.anthropic.com/))
- Python 3.9 or newer - Python 3.9 or newer
- Stable internet connection - Stable internet connection
## ⚡ Installation ## ⚡ Installation
### HACS Installation (Recommended) ### HACS Installation (Recommended)
1. Open HACS in Home Assistant 1. Open HACS in Home Assistant
2. Click the "+" button 2. Click on the three dots in the top right corner
3. Search for "HA Text AI" 3. Select "Custom repositories"
4. Click "Install" 4. Add `https://github.com/smkrv/ha-text-ai` as Integration
5. Restart Home Assistant 5. Click "Add"
6. Click on "Integrations" in HACS
7. Search for "HA Text AI"
8. Click "Download"
9. Restart Home Assistant
### Manual Installation ### Manual Installation
1. Download the latest release 1. Download the latest release
@@ -86,12 +101,15 @@ Transform your smart home experience with powerful AI assistance powered by Open
### Via YAML ### Via YAML
```yaml ```yaml
ha_text_ai: ha_text_ai:
api_key: !secret openai_api_key api_key: !secret ai_api_key
model: gpt-3.5-turbo model: gpt-3.5-turbo # or claude-3-sonnet
temperature: 0.7 temperature: 0.7
max_tokens: 1000 max_tokens: 1000
request_interval: 1.0 request_interval: 1.0
api_endpoint: https://api.openai.com/v1 # optional 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 ## 🛠️ Available Services
@@ -101,9 +119,10 @@ ha_text_ai:
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: "gpt-4o" # optional model: "claude-3-sonnet" # optional
temperature: 0.5 # optional temperature: 0.5 # optional
max_tokens: 500 # optional max_tokens: 500 # optional
system_prompt: "You are a sleep optimization expert" # optional
``` ```
### set_system_prompt ### set_system_prompt
@@ -128,107 +147,25 @@ service: ha_text_ai.clear_history
service: ha_text_ai.get_history service: ha_text_ai.get_history
data: data:
limit: 5 # optional limit: 5 # optional
filter_model: "gpt-4" # optional
``` ```
## 🔧 Advanced Examples [... rest of the README remains the same with updated FAQ section ...]
### Smart Energy Management
```yaml
automation:
alias: "AI Energy Optimization"
trigger:
platform: time_pattern
hours: "/2"
action:
- service: ha_text_ai.ask_question
data:
question: >
Current power usage: {{ states('sensor.total_power') }}W
Temperature: {{ states('sensor.indoor_temperature') }}°C
Time: {{ now().strftime('%H:%M') }}
Occupancy: {{ states('binary_sensor.occupancy') }}
Analyze current energy usage and suggest optimizations
considering comfort and efficiency.
temperature: 0.3
max_tokens: 200
- service: notify.mobile_app
data:
message: "{{ states.sensor.ha_text_ai.attributes.response }}"
```
### Contextual Lighting Control
```yaml
automation:
alias: "AI Lighting Assistant"
trigger:
platform: state
entity_id: binary_sensor.motion
variables:
context: >
Time: {{ now().strftime('%H:%M') }}
Light Level: {{ states('sensor.illuminance') }}
Room: {{ trigger.to_state.attributes.room }}
Activity: {{ states('input_select.current_activity') }}
Weather: {{ states('weather.home') }}
action:
- service: ha_text_ai.ask_question
data:
question: >
Based on this context:
{{ context }}
Suggest optimal lighting settings for current conditions.
model: gpt-3.5-turbo
temperature: 0.4
- service: scene.turn_on
data:
entity_id: >
{{ states.sensor.ha_text_ai.attributes.response | regex_findall('scene\.[a-z_]+') | first }}
```
## 📊 Performance Optimization
### Token Usage
- Use focused system prompts
- Implement response caching
- Clear history periodically
- Monitor token usage
### Response Time
- Adjust request_interval
- Use faster models for simple queries
- Implement timeout handling
- Cache frequent responses
### Memory Management
- Set appropriate history limits
- Clear unused contexts
- Monitor memory usage
- Use efficient data structures
## ❗ Troubleshooting
### API Issues
- Verify API key validity
- Check rate limits
- Monitor usage quotas
- Test endpoint accessibility
### Performance Issues
- Reduce max_tokens
- Increase request_interval
- Clear conversation history
- Check network connectivity
### Integration Issues
- Verify HA version compatibility
- Check component dependencies
- Review log files
- Update configuration
## 📘 FAQ ## 📘 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: 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?** **Q: How can I reduce API costs?**
A: Use GPT-3.5-Turbo for most queries, implement caching, and optimize token usage. A: Use GPT-3.5-Turbo for most queries, implement caching, and optimize token usage.