From f4b0ce902e4fe060215a12cee7068fbbbe7b5672 Mon Sep 17 00:00:00 2001 From: SMKRV Date: Tue, 19 Nov 2024 14:06:32 +0300 Subject: [PATCH] Release v1.0.3 --- README.md | 234 ++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 166 insertions(+), 68 deletions(-) diff --git a/README.md b/README.md index 565c235..ed8a4e8 100644 --- a/README.md +++ b/README.md @@ -7,154 +7,250 @@ ![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) [![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) +[![Community Forum](https://img.shields.io/badge/Community-Forum-blue.svg?style=flat-square)](https://community.home-assistant.io/t/ha-text-ai-integration)

-Transform your smart home experience with powerful AI assistance powered by OpenAI's GPT models +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.

--- ## ๐ŸŒŸ Features -- ๐Ÿง  **Advanced AI Integration**: Leverage OpenAI's powerful models (GPT-3.5, GPT-4) for smart home interactions -- ๐Ÿ’ฌ **Natural Language Control**: Control your home and get information using everyday language -- ๐Ÿ“ **Conversation Memory**: Maintain context with conversation history tracking -- โšก **Real-time Responses**: Get quick, contextual responses to your queries -- ๐ŸŽฏ **Customizable Behavior**: Fine-tune AI responses with adjustable parameters -- ๐Ÿ”’ **Secure Integration**: Your API key and data are handled securely -- ๐ŸŽจ **Flexible Configuration**: Easy setup with multiple configuration options -- ๐Ÿ”„ **Automation Ready**: Integrate AI responses into your automations +- ๐Ÿง  **Advanced AI Integration**: + - Support for latest GPT models + - Context-aware responses + - Multi-turn conversations +- ๐Ÿ’ฌ **Natural Language Control**: + - Control devices using everyday language + - Get detailed explanations and recommendations + - Natural conversation flow +- ๐Ÿ“ **Smart Memory Management**: + - Persistent conversation history + - Context-aware responses + - Customizable history limits +- โšก **Performance Optimized**: + - Efficient token usage + - Rate limit handling + - Response caching +- ๐ŸŽฏ **Advanced Customization**: + - Adjustable response parameters + - Custom system prompts + - Model selection per request +- ๐Ÿ”’ **Enhanced Security**: + - Secure API key storage + - Rate limiting protection + - Error handling +- ๐ŸŽจ **User Experience**: + - Intuitive configuration UI + - Detailed sensor attributes + - Rich service interface +- ๐Ÿ”„ **Automation Integration**: + - Event-driven responses + - Conditional logic support + - Template compatibility ## ๐Ÿ“‹ Prerequisites -- Home Assistant installation (Core, OS, Container, or Supervised) +- Home Assistant 2023.8.0 or newer - OpenAI API key ([Get one here](https://platform.openai.com/account/api-keys)) - Python 3.9 or newer +- Stable internet connection -## โšก Quick Start +## โšก Installation + +### HACS Installation (Recommended) +1. Open HACS in Home Assistant +2. Click the "+" button +3. Search for "HA Text AI" +4. Click "Install" +5. Restart Home Assistant ### Manual Installation -1. Download the repository -2. Copy `custom_components/ha_text_ai` to your `custom_components` directory +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 to `configuration.yaml`: +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_key: !secret openai_api_key + model: gpt-3.5-turbo + temperature: 0.7 + max_tokens: 1000 + request_interval: 1.0 + api_endpoint: https://api.openai.com/v1 # optional ``` -## โš™๏ธ Configuration Options - -| Option | Type | Default | Description | -|--------|------|---------|-------------| -| `api_key` | string | Required | Your OpenAI API key | -| `model` | string | `gpt-3.5-turbo` | AI model to use | -| `temperature` | float | `0.7` | Response creativity (0-2) | -| `max_tokens` | integer | `1000` | Maximum response length | -| `request_interval` | float | `1.0` | Minimum seconds between requests | -| `api_endpoint` | string | OpenAI default | Custom API endpoint URL | - ## ๐Ÿ› ๏ธ Available Services ### ask_question -Ask the AI assistant a question: ```yaml service: ha_text_ai.ask_question data: question: "What's the optimal temperature for sleeping?" - model: "gpt-4" # optional + model: "gpt-4o" # optional temperature: 0.5 # optional max_tokens: 500 # optional ``` ### set_system_prompt -Configure AI behavior: ```yaml service: ha_text_ai.set_system_prompt data: - prompt: "You are a home automation expert focused on energy efficiency" + prompt: | + You are a home automation expert focused on: + 1. Energy efficiency + 2. Comfort optimization + 3. Security considerations + Provide practical, actionable advice. ``` ### clear_history -Reset conversation history: ```yaml service: ha_text_ai.clear_history ``` ### get_history -Retrieve conversation history: ```yaml service: ha_text_ai.get_history data: limit: 5 # optional ``` -## ๐Ÿ”ง Practical Examples +## ๐Ÿ”ง Advanced Examples -### Smart Temperature Management +### Smart Energy Management ```yaml automation: + alias: "AI Energy Optimization" trigger: platform: time_pattern - hours: "/1" + hours: "/2" action: - service: ha_text_ai.ask_question - data: - question: > - Current temperature is {{ states('sensor.living_room_temperature') }}ยฐC. - Should I adjust the thermostat for optimal comfort and energy savings? + - 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 }}" ``` -### Smart Lighting Assistant +### Contextual Lighting Control ```yaml automation: + alias: "AI Lighting Assistant" trigger: platform: state - entity_id: binary_sensor.living_room_motion - to: 'on' - condition: - condition: template - value_template: "{{ states('sensor.illuminance') | float < 10 }}" + 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: > - Motion detected in living room with low light levels. - What's the best lighting scene to set based on the time of day? + - 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 }} ``` -## โ— Common Issues +## ๐Ÿ“Š Performance Optimization -### API Rate Limits -- Increase `request_interval` if hitting rate limits -- Consider upgrading your OpenAI plan -- Use caching for frequent queries - -### High Token Usage -- Reduce `max_tokens` parameter -- Clear conversation history regularly +### Token Usage - Use focused system prompts +- Implement response caching +- Clear history periodically +- Monitor token usage -### Connection Issues -- Check internet connectivity +### 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 -- Ensure endpoint accessibility +- 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 + +**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, API keys are stored securely and data is transmitted via encrypted connections. + +**Q: Can I use custom models?** +A: Yes, configure custom endpoints and models via configuration options. ## ๐Ÿค Contributing -Contributions are welcome! Please feel free to submit a Pull Request. +Contributions welcome! Please read our [Contributing Guide](CONTRIBUTING.md). 1. Fork the repository -2. Create your feature branch (`git checkout -b feature/AmazingFeature`) -3. Commit your changes (`git commit -m 'Add some AmazingFeature'`) -4. Push to the branch (`git push origin feature/AmazingFeature`) -5. Open a Pull Request +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 -This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. +MIT License - see [LICENSE](LICENSE) for details. --- @@ -162,4 +258,6 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file 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) +