From 886fed40db79f7a47e6ba02fdb2fef1edea3dc25 Mon Sep 17 00:00:00 2001 From: SMKRV Date: Mon, 18 Nov 2024 10:54:24 +0300 Subject: [PATCH] Update README.md --- README.md | 164 +++++++++++++++++++++++++++++++++++------------------- 1 file changed, 107 insertions(+), 57 deletions(-) diff --git a/README.md b/README.md index e6e2270..ffc65e7 100644 --- a/README.md +++ b/README.md @@ -1,78 +1,128 @@ -# HA text AI +# ๐Ÿค– HA text AI Integration for Home Assistant -This is a Home Assistant custom integration that allows you to interact with OpenAI's API and compatible endpoints to generate AI responses. +![GitHub release](https://img.shields.io/github/release/smkrv/ha_text_ai.svg) +![GitHub stars](https://img.shields.io/github/stars/smkrv/ha_text_ai.svg?style=social) +![GitHub forks](https://img.shields.io/github/forks/smkrv/ha_text_ai.svg?style=social) +![GitHub issues](https://img.shields.io/github/issues/smkrv/ha_text_ai.svg) + +This is a custom integration for Home Assistant that allows you to interact with OpenAI's text generation models. It provides a sensor entity to track the status of the integration and services to ask questions, view response history, and clear the history. ๐Ÿ“Š๐Ÿ” + +--- ## Features -- Configure all settings through the Home Assistant UI -- Support for OpenAI API and compatible endpoints -- Configurable parameters (temperature, max tokens, etc.) -- Request queue system to prevent API rate limiting -- Long response storage -- Multiple parallel questions support -- Real-time updates +- **Sensor Entity**: Track the readiness of the HA text AI integration. +- **Ask Question Service**: Submit questions to the AI and receive responses. +- **Clear History Service**: Erase the stored history of questions and responses. +- **Get History Service**: Retrieve the history of recent interactions. +- **Set System Prompt Service**: Configure a system prompt for all future AI questions. -## Installation +--- -### HACS Installation -1. Go to HACS in your Home Assistant installation -2. Click on "Integrations" -3. Click the "+" button -4. Search for "HA text AI" -5. Click "Install" -6. Restart Home Assistant +## Installation via HACS -### Manual Installation -1. Copy the `custom_components/ha_text_ai` directory to your Home Assistant's `custom_components` directory -2. Restart Home Assistant +1. **Install HACS** (if you haven't already): Follow the [HACS installation guide](https://hacs.xyz/docs/installation/prerequisites/) if you need to install HACS first. +2. **Add HA text AI Integration to HACS**: + - Open Home Assistant. + - Navigate to **HACS**. + - Click on **Integrations**. + - Click the **Explore & Add Repositories** button (โž•). + - Enter the repository URL: `https://github.com/smkrv/ha_text_ai` + - Click **Add repository**. +3. **Install**: + - In the list of available integrations, find **HA text AI**. + - Click on **Install**. -## Configuration +--- -1. Go to Configuration -> Integrations -2. Click "+" to add a new integration -3. Search for "HA text AI" -4. Enter your OpenAI API key and configure other settings +## Manual Installation -## Usage +1. **Download the repository**: + - Clone the repository to your Home Assistantโ€™s `config/custom_components` directory. + ```bash + git clone https://github.com/smkrv/ha_text_ai.git config/custom_components/ha_text_ai + ``` -### Service Calls -You can use the `ha_text_ai.ask_question` service to ask questions: +2. **Restart Home Assistant**: + - Go to **Configuration** -> **Server Controls** in Home Assistant and restart your Home Assistant instance. -```yaml -service: ha_text_ai.ask_question -data: - question: "What is the weather like today?" -``` +3. **Configuration**: + - Navigate to **Configuration** -> **Integrations** in Home Assistant. + - Click **Add Integration** (โž•). + - Search for **HA text AI** and click **Configure**. + - Enter your OpenAI API key and other optional settings as prompted. -### Automation Example -```yaml -automation: - - alias: "Daily Weather Question" - trigger: - platform: time - at: "07:00:00" - action: - - service: ha_text_ai.ask_question - data: - question: "What's the weather forecast for today?" -``` +--- ## Configuration Options -| Option | Description | Default | -|--------|-------------|---------| -| `api_key` | Your OpenAI API key | Required | -| `model` | The AI model to use | gpt-3.5-turbo | -| `temperature` | Response randomness (0-1) | 0.7 | -| `max_tokens` | Maximum response length | 1000 | -| `api_endpoint` | Custom API endpoint | https://api.openai.com/v1 | -| `request_interval` | Minimum time between requests | 1.0 | +- **API Key**: Your OpenAI API key +- **Model**: The OpenAI model to use (default: `gpt-3.5-turbo`) +- **Temperature**: Controls the randomness of the output. Lower values make the output more deterministic (default: `0.7`) +- **Max Tokens**: Maximum length of the response (default: `1000`) +- **API Endpoint**: Custom endpoint URL for the OpenAI API (default: `https://api.openai.com/v1`) +- **Request Interval**: Time interval for polling the API (in seconds, default: `1.0`) -## Support +--- -For bugs and feature requests, please create an issue on GitHub. +## Services + +### 1. Ask Question +**Service:** `ha_text_ai.ask_question` +- **Description**: Ask a question to the integrated AI and receive a response. +- **Parameters**: + - `question`: The question or prompt to send to the AI (required) + - `model`: Override the default model for this question (optional) + - `temperature`: Adjust randomness in the response (0.0-1.0, optional) + - `max_tokens`: Limit the length of the response (optional) + +### 2. Clear History +**Service:** `ha_text_ai.clear_history` +- **Description**: Clear the stored history of questions and responses. + +### 3. Get History +**Service:** `ha_text_ai.get_history` +- **Description**: Retrieve the history of recent interactions. +- **Parameters**: + - `limit`: Maximum number of history items to return (default: `10`) + +### 4. Set System Prompt +**Service:** `ha_text_ai.set_system_prompt` +- **Description**: Set a system prompt to guide the AI's behavior in future interactions. +- **Parameters**: + - `prompt`: The system prompt to set (required) + +--- + +## Advanced Usage + +- **Sensor State**: The sensor entity `sensor.ha_text_ai` will show `Ready` if the integration is configured and operational, otherwise it will show `Not Ready`. +- **Attributes**: When the sensor state is `Ready`, it provides attributes: + - `question`: The last question asked. + - `response`: The response to the last question. + - `last_updated`: Timestamp of the last successful update from the API. + +--- + +## Logs & Debugging + +- To view logs and debug issues, check the Home Assistant logs under **Configuration** -> **Logs**. + +--- + +## Contributing + +Feel free to contribute to this project! Open an issue or submit a pull request with any questions, improvements, or bug fixes. + +- **Issues**: [github.com/smkrv/ha_text_ai/issues](https://github.com/smkrv/ha_text_ai/issues) +- **Pull Requests**: [github.com/smkrv/ha_text_ai/pulls](https://github.com/smkrv/ha_text_ai/pulls) + +--- ## License -This project is licensed under the MIT License. -``` +This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details. + +--- + +๐Ÿš€ Ready to use your AI-powered assistant in Home Assistant? Just set up and start asking questions through the integrated services!