mirror of
https://github.com/AtHeartEngineering/ai_automation_suggester.git
synced 2026-01-09 22:27:55 -05:00
Update README.md
This commit is contained in:
Graham Hosking
196
README.md
196
README.md
@@ -1,154 +1,124 @@
|
||||
<!-- Buy‑me‑a‑coffee at the very top -->
|
||||
<p align="center">
|
||||
<a href="https://www.buymeacoffee.com/ITSpecialist" target="_blank">
|
||||
<img src="https://img.shields.io/badge/Buy me a coffee-Support Dev-yellow?style=for-the-badge&logo=buy-me-a-coffee" alt="Buy Me A Coffee">
|
||||
</a>
|
||||
</p>
|
||||
|
||||
# AI Automation Suggester
|
||||
|
||||
[](https://www.buymeacoffee.com/ITSpecialist)
|
||||
[](https://github.com/ITSpecialist111/ai_automation_suggester/actions)
|
||||
[](https://github.com/ITSpecialist111/ai_automation_suggester/actions)
|
||||
[](https://github.com/ITSpecialist111/ai_automation_suggester/releases)
|
||||
[](https://hacs.xyz/)
|
||||
[]()
|
||||
[]()
|
||||
[]()
|
||||
[]()
|
||||
|
||||
> **Current version:** 1.3.1 • **Tested on Home Assistant ≥ 2024.1**
|
||||
|
||||
An integration for Home Assistant that leverages AI language models to understand your unique home environment and propose intelligent automations. By analysing your entities, devices, areas, and **existing automations**, the AI Automation Suggester surfaces new, context‑aware ideas that streamline home management and boost efficiency, comfort and security.
|
||||
An **AI‑powered assistant** for Home Assistant that *studies* your entities, areas, devices and existing automations, then proposes fresh YAML you can drop straight into your system.
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Quick highlights (v1.3.1)
|
||||
## ✨ Why does this exist?
|
||||
|
||||
* **`description` & `yaml_block` split** – dashboards can now show prose *and* raw YAML separately.
|
||||
* Supports **OpenAI, Anthropic, Google, Groq, LocalAI, Ollama, Mistral AI, Perplexity AI**.
|
||||
* Service `ai_automation_suggester.generate_suggestions` accepts `all_entities`, `domains`, `entity_limit`, `custom_prompt`.
|
||||
* Two sensors exposed: suggestions + provider status.
|
||||
> *“I’ve added 200+ entities… now what?”*
|
||||
|
||||
Building a truly smart home usually stalls at the same road‑block:
|
||||
|
||||
* **Too many possibilities** – every new sensor or light multiplies the ways things *could* interact.
|
||||
* **Writer’s block** – YAML automations look simple until you try capturing real‑world nuance (presence, time, energy prices…).
|
||||
* **Maintenance overload** – even seasoned users forget to revisit old routines when hardware or habits change.
|
||||
|
||||
The result: **under‑automated houses** full of unrealised potential.
|
||||
|
||||
### The Fix – an Automation Copilot
|
||||
|
||||
AI Automation Suggester acts like a consultant who:
|
||||
|
||||
1. **Inventories** your Home Assistant (entities, devices, areas and existing automations).
|
||||
2. **Spots gaps & synergies** – e.g. *“You have a motion sensor in the hallway and a door sensor nearby; combine them for smarter lighting.”*
|
||||
3. **Drafts ready‑to‑paste YAML** including triggers / conditions / actions referencing your actual `entity_id`s.
|
||||
4. Repeats on demand, so ideas evolve as your home evolves.
|
||||
|
||||
You still decide what runs – the integration just boots you past the blank‑page stage.
|
||||
|
||||
---
|
||||
|
||||
## 1 • Purpose & problem statement
|
||||
## 🚀 How it works
|
||||
|
||||
Smart‑homes grow complex fast. Which automations actually help?
|
||||
**AI Automation Suggester = personal automation consultant** spotting:
|
||||
|
||||
* Energy‑saving tweaks
|
||||
* Security gaps
|
||||
* Quality‑of‑life conveniences
|
||||
* Maintenance reminders
|
||||
|
||||
with ready‑to‑paste YAML.
|
||||
| Step | What happens? |
|
||||
|------|---------------|
|
||||
| 1. Snapshot | On a manual trigger or scheduled automation the integration collects a **randomised sample** (size configurable) of your entities & attributes plus a list of existing automations. |
|
||||
| 2. Prompt building | That snapshot is embedded into a **system prompt** describing your house. You can append a *custom prompt* such as “focus on energy‑saving”. |
|
||||
| 3. Provider call | The prompt is sent to your chosen model ‑ OpenAI, Anthropic, Google, Groq, LocalAI, Ollama, Mistral or Perplexity. |
|
||||
| 4. Parsing | The raw LLM response is stored on a sensor attribute:<br> `description` (prose) · `yaml_block` (detected ```yaml ... ``` code) · full `suggestions` |
|
||||
| 5. Surface | A persistent notification appears. Markdown cards can show the attributes for a no‑code dashboard. |
|
||||
|
||||
---
|
||||
|
||||
## 2 • How it works
|
||||
## 🏆 Benefits
|
||||
|
||||
1. **Snapshot** – entity/device/area/automation metadata collected.
|
||||
2. **AI call** – prompt sent to chosen provider.
|
||||
3. **Result parsing** – splits into `description` and `yaml_block`.
|
||||
4. **Notification & sensors** – easy review in HA UI or dashboards.
|
||||
* **Minutes, not hours** – go from idea to working automation fast.
|
||||
* **Context‑aware** – suggestions include area/device info so you’ll see *living‑room‑specific* rules, not boiler‑plate.
|
||||
* **Model‑agnostic** – cloud keys or fully‑local inference, your choice.
|
||||
* **Safe to try** – nothing is executed automatically; you review & paste.
|
||||
|
||||
---
|
||||
|
||||
## 3 • Features
|
||||
## 📦 Features (v1.3.1)
|
||||
|
||||
| Category | Details |
|
||||
|----------|---------|
|
||||
| **Multi‑provider** | OpenAI, Anthropic, Google, Groq, LocalAI, Ollama, Mistral AI, Perplexity AI |
|
||||
| **Custom scope** | Random entity sampling, domain filter, entity limit |
|
||||
| **Custom prompts**| Steer suggestions (“focus on off‑peak energy”) |
|
||||
| **Persistent results** | Stored as sensor attributes |
|
||||
| **Dashboard‑ready** | `description` & `yaml_block` attributes |
|
||||
* Multi‑provider back‑end (OpenAI, Anthropic, Google, Groq, LocalAI, Ollama, Mistral, Perplexity).
|
||||
* Service `ai_automation_suggester.generate_suggestions` with flags:<br>
|
||||
`all_entities`, `domains`, `entity_limit`, `custom_prompt`.
|
||||
* Two diagnostics sensors: **Suggestions** & **Provider Status**.
|
||||
* Built‑in example automations (new‑entity & weekly review).
|
||||
* Dashboard‑friendly attributes `description` & `yaml_block` (since 1.3.0).
|
||||
|
||||
---
|
||||
|
||||
## 4 • Prerequisites
|
||||
## 🛠️ Installation
|
||||
|
||||
* **Home Assistant ≥ 2024.1**
|
||||
* Cloud LLMs: API keys
|
||||
* Local LLMs: LocalAI/Ollama server reachable by HA
|
||||
### HACS (recommended)
|
||||
|
||||
---
|
||||
1. In HACS › Integrations › **Search “AI Automation Suggester”**.
|
||||
2. Install → Restart HA → Settings › Devices & Services → “+” → Add Integration.
|
||||
|
||||
## 5 • Installation
|
||||
### Manual
|
||||
|
||||
### a) HACS (recommended)
|
||||
|
||||
1. HACS → *Integrations* → search “AI Automation Suggester”.
|
||||
2. Install → restart HA.
|
||||
|
||||
### b) Manual
|
||||
|
||||
1. Download the release ZIP.
|
||||
2. Copy `custom_components/ai_automation_suggester` into `config/custom_components/`.
|
||||
3. Restart HA.
|
||||
|
||||
---
|
||||
|
||||
## 6 • Configuration
|
||||
|
||||
1. Settings → Devices & Services → **Add Integration** → AI Automation Suggester.
|
||||
2. Select provider + credentials.
|
||||
3. Optionally adjust `model` and `max_tokens`.
|
||||
4. Repeat for multiple providers.
|
||||
|
||||
---
|
||||
|
||||
## 7 • Using the service
|
||||
|
||||
| Field | Purpose |
|
||||
|-------|---------|
|
||||
| `provider_config` | Target a specific config entry |
|
||||
| `all_entities` | Analyse every entity vs. only new ones |
|
||||
| `domains` | Domain list or comma‑string |
|
||||
| `entity_limit` | Cap for token control |
|
||||
| `custom_prompt` | Extra instructions for the LLM |
|
||||
|
||||
---
|
||||
|
||||
## 8 • Dashboard snippets
|
||||
|
||||
### Description card
|
||||
|
||||
```yaml
|
||||
content: >
|
||||
**Status:** {{ states('sensor.ai_automation_suggestions_google') }}
|
||||
|
||||
**Last update:** {{ state_attr('sensor.ai_automation_suggestions_google','last_update') }}
|
||||
|
||||
---
|
||||
|
||||
{{ state_attr('sensor.ai_automation_suggestions_google','description') }}
|
||||
```bash
|
||||
custom_components/
|
||||
└── ai_automation_suggester
|
||||
├── __init__.py
|
||||
├── ...
|
||||
```
|
||||
|
||||
### YAML block card
|
||||
|
||||
```yaml
|
||||
content: >
|
||||
{% set y = state_attr('sensor.ai_automation_suggestions_google','yaml_block') %}
|
||||
{% if y %}
|
||||
```yaml
|
||||
{{ y }}
|
||||
```
|
||||
{% else %}
|
||||
_No YAML block in last suggestion._
|
||||
{% endif %}
|
||||
```
|
||||
Restart HA and add via UI.
|
||||
|
||||
---
|
||||
|
||||
## 9 • Troubleshooting
|
||||
## ✍️ Usage
|
||||
|
||||
* **No suggestions received** → check provider logs / API quota or lower `entity_limit`.
|
||||
* **Provider status = error** → double‑check endpoint / model name.
|
||||
* **Template errors** → reference `description` or `yaml_block`, not `suggestions`.
|
||||
* **Manual**: Developer Tools › Services › call `ai_automation_suggester.generate_suggestions`.
|
||||
* **Automatic**: Enable the included example automations or create your own triggers.
|
||||
* **Dashboard**:
|
||||
*Description*: `{{ state_attr('sensor.ai_automation_suggestions_<provider>', 'description') }}`
|
||||
*YAML*: see docs for full card example.
|
||||
|
||||
---
|
||||
|
||||
## 10 • Roadmap
|
||||
## 🧩 Troubleshooting
|
||||
|
||||
* One‑click “Create automation”
|
||||
* Feedback loop for smarter prompts
|
||||
* More languages
|
||||
| Symptom | Check |
|
||||
|---------|-------|
|
||||
| “No suggestions available” | API key valid? provider status sensor error? try smaller `entity_limit`. |
|
||||
| Provider Status `error` | Inspect HA log for `processing error:` lines. |
|
||||
| Deprecation warning (options flow) | Fixed in 1.3.1 – update! |
|
||||
|
||||
---
|
||||
|
||||
## 11 • License & support
|
||||
## 🤝 Contributing & Support
|
||||
|
||||
MIT license. Not affiliated with Home Assistant or any AI provider.
|
||||
* Issues & PRs welcome.
|
||||
* Translations live under `custom_components/.../translations/`.
|
||||
* If this project saves you time, ☕ is always appreciated – hit the coffee button up top.
|
||||
|
||||
Found it helpful? **[Buy me a coffee ☕](https://www.buymeacoffee.com/ITSpecialist)** – keeps the tokens flowing!
|
||||
---
|
||||
|
||||
© 2025 MIT License – Not affiliated with Home Assistant or listed providers.
|
||||
|
||||
Reference in New Issue
Block a user