# itspecialist111/ai_automation_suggester architecture

> Architecture diagram of the GitHub repository itspecialist111/ai_automation_suggester, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/itspecialist111/ai_automation_suggester
- Repository: https://github.com/itspecialist111/ai_automation_suggester

## Overview

##### Project Type and Purpose
- This is a **Home Assistant custom integration** (a plugin) named “AI Automation Suggester.”
- Purpose: Collect Home Assistant state (entities, devices, areas, existing automations), build a prompt, call external AI providers, parse AI responses, and surface YAML suggestions via sensors, notifications, and a custom Lovelace card.

##### File Structure
- Top-level:
- `.github/workflows/` – CI: HACS, hassfest, lint/validate.
- `custom_components/ai_automation_suggester/` – the integration’s code.
- `custom_components/dashboard/` – example dashboard text.
- `hacs.json`, `requirements.txt`, `README.md`, `LICENSE`
- Inside `custom_components/ai_automation_suggester`:
- Python modules: `__init__.py`, `config_flow.py`, `coordinator.py`, `sensor.py`, `const.py`
- `manifest.json`, `services.yaml` – integration metadata & service definitions
- `automations/` – built-in YAML automations (new-entity, weekly reviews)
- `www/ai-automation-suggester-card.js` – custom Lovelace card
- i18n: `strings.json`, `translations/*.json`

##### Read README Insights
- Describes a 5-step process: Snapshot → Prompt Building → Provider Call → Parsing → Surface
- Lists supported AI providers (OpenAI, Anthropic, etc.)
- Explains sensors (`sensor.ai_automation_suggestions_<provider>`, `sensor.ai_provider_status_<provider>`), service (`ai_automation_suggester.generate_suggestions`), and dashboard usage.

##### Final Recommendations
- Be exhaustive but clear: capture every integration point (services, sensors, automations, UI).
- Critical configuration points (e.g., `manifest.json`, `services.yaml`).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User and Core
    User["User"]:::ui
    HACore["Home Assistant Core"]:::core

    %% Integration Subgraph
    subgraph "AI Automation Suggester Integration"
        ConfigFlow["AI Automation Suggester Config Flow"]:::integration
        Service["Service: generate_suggestions"]:::integration
        Coordinator["Coordinator"]:::integration
        Sensors["Sensor Entities"]:::integration
        Manifest["Integration Metadata (manifest.json)"]:::integration
        Const["Constants & Provider Adapters"]:::integration
        I18nStrings["Internationalization Strings"]:::integration
        Translations["Translation Files"]:::integration
        LovelaceCard["Lovelace Card"]:::integration
        subgraph "Built-in Automations"
            NewEntity["New-Entity Automation"]:::integration
            WeeklyReview["Weekly-Review Automation"]:::integration
        end
    end

    %% External
    AIProviders["External AI Providers"]:::external

    %% UI Outputs
    Notification["Persistent Notification"]:::ui
    DashboardExample["Example Dashboard Text"]:::ui

    %% Flows
    User -->|"Configure"| ConfigFlow
    ConfigFlow -->|"Store config"| HACore

    NewEntity -->|"Trigger"| Service
    WeeklyReview -->|"Trigger"| Service
    Service -->|"invoke generate_suggestions"| Coordinator
    Coordinator -->|"snapshot: query entities, devices, automations"| HACore
    Coordinator -->|"build prompt"| Const
    Const -->|"use strings.json & translations"| I18nStrings
    I18nStrings --> Translations
    Coordinator -->|"HTTP call with prompt"| AIProviders
    AIProviders -->|"raw AI response"| Coordinator
    Coordinator -->|"parse description & yaml"| Sensors
    Sensors -->|"update attributes"| Notification
    Sensors -->|"provide data"| LovelaceCard
    Sensors -->|"provide data"| DashboardExample

    %% Click Events
    click ConfigFlow "https://github.com/itspecialist111/ai_automation_suggester/blob/main/custom_components/ai_automation_suggester/config_flow.py"
    click Coordinator "https://github.com/itspecialist111/ai_automation_suggester/blob/main/custom_components/ai_automation_suggester/coordinator.py"
    click Service "https://github.com/itspecialist111/ai_automation_suggester/blob/main/custom_components/ai_automation_suggester/services.yaml"
    click Sensors "https://github.com/itspecialist111/ai_automation_suggester/blob/main/custom_components/ai_automation_suggester/sensor.py"
    click Manifest "https://github.com/itspecialist111/ai_automation_suggester/blob/main/custom_components/ai_automation_suggester/manifest.json"
    click Const "https://github.com/itspecialist111/ai_automation_suggester/blob/main/custom_components/ai_automation_suggester/const.py"
    click NewEntity "https://github.com/itspecialist111/ai_automation_suggester/blob/main/custom_components/ai_automation_suggester/automations/new-entity-automation.yaml"
    click WeeklyReview "https://github.com/itspecialist111/ai_automation_suggester/blob/main/custom_components/ai_automation_suggester/automations/weekly-review-automation.yaml"
    click LovelaceCard "https://github.com/itspecialist111/ai_automation_suggester/blob/main/custom_components/ai_automation_suggester/www/ai_automation_suggester/ai-automation-suggester-card.js"
    click I18nStrings "https://github.com/itspecialist111/ai_automation_suggester/blob/main/custom_components/ai_automation_suggester/strings.json"
    click Translations "https://github.com/itspecialist111/ai_automation_suggester/blob/main/custom_components/ai_automation_suggester/translations/en.json"
    click NewEntity "https://github.com/itspecialist111/ai_automation_suggester/blob/main/.github/workflows/hacs.yaml"
    click WeeklyReview "https://github.com/itspecialist111/ai_automation_suggester/blob/main/.github/workflows/hassfest.yaml"
    click DashboardExample "https://github.com/itspecialist111/ai_automation_suggester/blob/main/custom_components/dashboard/seperate dashboard.txt"

    %% Styles
    classDef core fill:#ADD8E6,stroke:#000;
    classDef integration fill:#98FB98,stroke:#000;
    classDef external fill:#FFA500,stroke:#000;
    classDef ui fill:#D3D3D3,stroke:#000;
```
