ha-selora-ai: Instructions file for Claude Code

Selora AI — Home Assistant Integration

Read by AI coding assistants on every session, so it holds only what applies repo-wide. Record a rule and its reason, not the story of how it was found (that belongs in the commit message), and nothing the code already says — what a module does belongs in its docstring, setup and deployment in CONTRIBUTING.md, a single feature's rules in docs/dev/.

A custom integration (custom_components/selora_ai/) that analyzes a home's devices and usage with an LLM (Selora Cloud, Selora AI Local, Anthropic, Gemini, OpenAI, OpenRouter, Ollama), proposes automations, scenes and dashboards, and takes natural-language commands from its own panel, from Assist, and over MCP.

Conventions

Python

• Python 3.14 (CI also runs 3.13), async throughout, from __future__ import annotations in every file.
• Fully typed, modern syntax (str | None). Use the TypedDicts in types.py rather than dict[str, Any]; bare Any only for genuinely dynamic data (raw external JSON, HA store loads). Annotation-only imports go under TYPE_CHECKING.
• _LOGGER = logging.getLogger(__name__).
• Catch specific exceptions, never bare except Exception.
• No secrets in code — API keys come from the config entry.
• uuid.uuid4() for ids, never hashlib.md5 (SAST flags it).
• Don't import dataclasses.field unless it is used.

Home Assistant

• Config entries carry entry_type: "llm_config" or "device_onboarding". The first entry configures the LLM; "Add Entry" goes straight to device discovery.
• Config-flow step ids must match keys in strings.json.
• Entities use _attr_has_entity_name = True and reference the hub device (DOMAIN, "selora_ai_hub").
• Lovelace is written through its API (LovelaceStorage.async_save), never by file.
• Never auto-accept discovered devices; never auto-configure an API key.
• A startup deferral is a TIMER, never a task that sleeps out its own delay. hass.async_create_task registers the task, so bootstrap, every entry reload and every test's async_block_till_done() wait for it — await asyncio.sleep(120) in a task made a 400ms test take 120s, and checking the feature flag after the sleep does not help. Arm with async_call_later, fire the work with async_create_background_task (which async_block_till_done() does not wait on), cancel the timer on unload before the first await, and let the callback tolerate a torn-down entry. Patterns: health_monitor.py, insights_audit.py, insights_export.py. tests/test_startup_delays.py guards by TIMEOUT — a regression makes a test slow, not red.