ha-selora-ai: Instructions file for Claude Code

Selora AI — Home Assistant Integration

This file is read by AI coding assistants (Claude Code, Zencoder, Copilot, etc.) to maintain consistency across developers and models. Keep it up to date.

What This Is

A custom Home Assistant integration (custom_components/selora_ai/) that acts as a "smart butler":

• Analyzes device states and usage patterns via LLM — Selora AI (Selora Cloud, or the on-device Selora AI Local model), Anthropic Claude, Google Gemini, OpenAI, OpenRouter, or local Ollama
• Auto-generates HA automations (disabled, prefixed [Selora AI] for user review)
• Accepts natural language commands via the Selora panel and Home Assistant Assist
• Discovers and onboards network devices during initial setup

Architecture

HA entity registry / state machine / recorder (SQLite)
    |
    v
DataCollector  ──snapshot──>  LLMClient (Selora Cloud / Selora Local / Anthropic / Gemini / OpenAI / OpenRouter / Ollama)
    |                              |
    |                         suggestions
    v                              v
logging + sensors         automations.yaml (disabled) + reload

Project Structure

custom_components/selora_ai/
├── __init__.py          # Integration setup/teardown, entry routing
├── config_flow.py       # UI config flow (LLM setup → device discovery → area assignment → results)
├── collector.py         # Hourly data collection + LLM automation writer
├── llm_client/          # LLM facade package (client, prompts, parsers, intent, command_policy, lang_detect, state_filter, usage)
├── providers/           # Pluggable LLM backends (Selora Cloud/Local, Anthropic, Gemini, OpenAI, OpenRouter, Ollama)
├── device_manager.py    # Device discovery, pairing, area assignment, dashboard generation
├── conversation.py      # Assist Conversation Agent — routes natural language to HA service calls
├── automation_utils.py  # Validation, risk assessment, YAML I/O, async automation CRUD
├── automation_normalize.py # Pure payload reshaping: field coercion, null-dropping, window merging
├── automation_store.py  # Lifecycle + versioning for [Selora AI] automations
├── group_manager.py     # HA group-helper CRUD (drives HA's own `group` config flow)
├── dashboard_manager.py # Lovelace view/card read + edit (chat tool surface)
├── registry_manager.py  # Area/floor/entity/device registry reads + writes, helper inventory
├── script_manager.py    # scripts.yaml CRUD (mapping, not a list — unlike automations)
├── label_manager.py     # Label registry + delta assignment across entities/devices/areas
├── diagnostics_tools.py # Read-only: system_log errors, automation run traces
├── code_stamp.py        # Source-signature skew detection (restart-required handshake)
├── scene_store.py       # Scene creation + persistence
├── websocket/           # Panel websocket handlers, one module per domain (registered lazily)
├── button.py            # Hub action buttons (Discover, Scan, Cleanup, Reset)
├── sensor.py            # Hub sensors (Status, Devices, Discovery, Last Activity)
├── selora_auth.py       # Multi-auth orchestration (HA token, MCP token, Selora JWT)
├── mcp_token_store.py   # Local MCP API token store (CRUD, hash-only storage)
├── telemetry.py         # Anonymous, opt-in repair-counter telemetry (PostHog)
├── types.py             # Shared TypedDict definitions (automations, patterns, suggestions, etc.)
├── const.py             # Constants, config keys, known integrations database
├── manifest.json        # HA integration manifest
├── strings.json         # UI strings for config flow
├── translations/         # HA-side translations (en, fr, de, es, it, nl, hu, pt, ru, ja, ko, zh-Hans, zh-Hant) — all keys must match strings.json
├── brand/               # Logo and icon assets
└── frontend/
    └── src/
        ├── panel.js                  # LitElement host (properties, lifecycle, render dispatch)
        └── panel/
            ├── render-automations.js # Automation list, cards, flowchart, unavailable modal
            ├── render-chat.js        # Chat messages, YAML editor, new-automation dialog
            ├── render-settings.js    # Settings tab
            ├── render-telemetry-consent.js # One-time telemetry opt-in banner
            ├── render-stale-code-notice.js  # Restart/reload-required banner
            ├── version-actions.js    # Code-skew handshake (unknown command ⇒ restart)
            ├── render-suggestions.js # Suggestion cards
            ├── render-version-history.js # Version history drawer + diff viewer
            ├── stale-automations.js  # Stale detection helpers + stale modal/detail
            ├── automation-crud.js    # CRUD websocket calls
            ├── automation-management.js # Bulk edit, enable/disable, filter
            ├── session-actions.js    # Session list actions
            ├── suggestion-actions.js # Accept/dismiss/snooze suggestion actions
            ├── chat-actions.js       # Send message, streaming
            └── styles/               # CSS-in-JS style modules