AI Automation Suggester

The AI Automation Suggester is a Home Assistant custom integration that generates automation suggestions by analyzing the context of entities, devices, areas, and existing automations.

Core Features:

• Sensor Platform: Exposes a sensor for automation suggestions.
• Service: Provides a generate_suggestions service.
• Notifications: Uses persistent notifications for user alerts.
• Configuration: Supports configuration and options flows for setup.
• UI: Includes a custom Lovelace card for displaying suggestions.
• Multi-Provider Support: Directly supports a wide range of AI providers including OpenAI, Azure OpenAI, Anthropic, Google, Groq, LocalAI, Ollama, Mistral, Perplexity, and OpenRouter.

The suggestion generation process is being refactored into a modular pipeline to improve reliability and prevent issues like truncated output or missing YAML. The pipeline consists of:

1. Context Collection (context.py): Gathers entities, areas, devices, existing automations, and optional YAML content.
2. Filtering (filters.py): Applies inclusion/exclusion rules for domains, areas, devices, entities, and availability status.
3. Prompt Construction (prompt.py): Builds prompt sections, selects the target language, enforces input budgets, and summarizes oversized context.
4. Parsing & Validation (suggestions.py): Parses structured responses from providers, validates YAML blocks, records warnings, and manages history.
5. Orchestration (coordinator.py): Man/orchestrates refreshes and updates Home Assistant sensors.

The integration provides (or is moving toward) granular control over the automation analysis process. Users can manage the scope of suggestions through:

• Scope Filtering: Exclude specific domains, areas, devices, or entities from being analyzed.
• Entity Status: Ability to ignore disabled or unavailable entities.
• Language Selection: Separating UI translation from the AI output language (prompt/output language can be selected via Home Assistant language or an explicit option).
• Customization: Using a persistent custom system prompt field to influence suggestion quality.

The integration uses structured output as a primary parsing strategy to ensure reliable automation suggestions.

Supported Methods:

• JSON/JSON Schema Mode: Supported by OpenAI, Gemini, Mistral, Perplexity, and OpenRouter. These use provider-specific parameter names (e.g., response_mime_type for Gemini).
• Markdown Fenced YAML Fallback: Used as a fallback mechanism for older models or local deployments that do not support native structured output modes.

When selecting a model, ensure it supports the required structured output format to avoid parsing errors.

To improve the relevance and quality of automation suggestions, the following features are planned:

Entity Filtering

Users will be able to use include/exclude filters for:

• Domains
• Areas
• Devices
• Entities
• Disabled entities
• Hidden entities
• Unavailable entities

Prompt Customization

• Persistent Custom System Prompt: A global option for the system prompt.
• Per-service Extra Prompt: Ability to add specific context when calling a service.

The project is moving toward a provider abstraction layer to handle the diversity of LLM endpoints (OpenAI, Anthropic, Google, Ollama, OpenRouter, etc.). Instead of a single dispatch dictionary, each provider will implement a shared contract to manage its own unique behaviors.

Key components of the provider layer include:

• ProviderConfig: Normalized settings derived from user configuration.
• ProviderCapabilities: Flags indicating support for features like OpenAI-compatible chat, Responses API, streaming, custom headers, JSON/schema mode, and specific token parameter names.
• ModelCapabilities: Metadata for specific models, including context window size, max output tokens, and structured-output support.
• BaseProvider: An interface defining core methods: validate(), generate(), parse_response(), and redact_for_diagnostics().

Depending on your installation method, follow these steps to update:

• HACS Installation: Update directly through the HACS interface within Home Assistant.
• Manual Installation:
  1. Download the latest version of the files from the repository.
  2. Replace the existing files in your custom_components/ai_automation_suggester folder.
  3. Restart Home Assistant.

To install without HACS:

1. Download the repository contents.
2. Copy the custom_components/ai_automation_suggester folder into your Home Assistant custom_components directory.

   <homeassistant_config_dir>/
   └── custom_components/
       └── ai_automation_suggester/
           ├── __init__.py
           └── ...

3. Restart Home Assistant.
4. Go to Settings → Devices & Services → + Add Integration and search for AI Automation Suggester.

After installation, add the integration via the Home Assistant UI (Settings → Devices & Services → + Add Integration → AI Automation Suggester).

The setup wizard requires:

• AI Provider: Select from the dropdown (e.g., OpenAI, Anthropic, Google, Ollama, etc.).
• API Keys or Endpoint: Provide credentials or the local server URL.
• Model: Choose the specific model variant.
• Max Tokens: Define the maximum length of the AI's response.
• Custom System Prompt (Optional): Provide a prompt to guide the AI's perspective (e.g., "You are an expert in energy-saving automations.").

Settings can be adjusted later via the integration options in the Devices & Services menu.