ha-actronair-neo

Imported from ruaan-deysel/ha-actronair-neo (AGENTS.md). Install upstream with npx skills add ruaan-deysel/ha-actronair-neo. Copyright stays with the author.

AI Agent Instructions

This document provides guidance for AI coding agents working on the ActronAir Neo Home Assistant custom integration project.

Project Overview

This is a Home Assistant custom integration for controlling ActronAir Neo air conditioning systems via the ActronAir cloud API.

Integration details:

• Domain: actronair_neo
• Title: ActronAir Neo
• Class prefix: ActronAirNeo
• Repository: ruaan-deysel/ha-actronair-neo
• iot_class: cloud_polling

Key directories:

• custom_components/actronair_neo/ — Main integration code
• config/ — Home Assistant configuration for local testing
• tests/ — Unit and integration tests
• script/ — Development and validation scripts

Local Home Assistant instance:

Always use the project's scripts — do NOT craft your own hass, pip, pytest, or similar commands. The scripts handle virtual environments, Python paths, and environment setup that raw commands miss.

Start Home Assistant:

script/develop

Validate code before committing:

script/lint

Run tests:

script/test
script/test --cov           # with coverage
script/test --cov-html      # HTML report in htmlcov/

Other useful scripts:

script/check          # type-check + lint-check + spell-check (before commits)
script/clean          # clean build artifacts
script/type-check     # Pyright type checking
script/spell          # spell check with auto-fix
script/help           # list all available scripts
script/setup/reset    # reset HA config to fresh state

Reading logs:

• Live: Terminal where script/develop runs
• File: config/home-assistant.log (most recent), config/home-assistant.log.1 (previous)

Adjust log levels for debugging in config/configuration.yaml:

logger:
  default: info
  logs:
    custom_components.actronair_neo: debug

Context-specific instructions:

If you're using GitHub Copilot, path-specific instructions in .github/instructions/*.instructions.md provide additional guidance for specific file types. This document serves as the primary reference for all agents.

Other agent entry points:

• Claude Code: See CLAUDE.md (pointer to this file)
• Gemini: See GEMINI.md (pointer to this file)
• GitHub Copilot: See .github/copilot-instructions.md (compact version of this file)

Working With Developers

When Instructions Conflict With Requests

If a developer requests something that contradicts these instructions:

1. Clarify the intent — Ask if they want you to deviate from documented guidelines
2. Confirm understanding — Restate what you understood to avoid misinterpretation
3. Suggest instruction updates — If this represents a permanent change in approach, offer to update these instructions
4. Proceed once confirmed — Follow the developer's explicit direction after clarification

Maintaining These Instructions

Instructions should evolve as the project matures:

• Refine guidelines based on actual project needs
• Remove outdated rules that no longer apply
• Consolidate redundant sections to prevent bloat

Propose updates when:

• You notice repeated deviations from documented patterns
• Instructions become outdated or contradict actual code
• New patterns emerge that should be standardized

Documentation vs. Instructions

Three types of content with clear separation:

1. Agent Instructions — How AI should write code (.github/instructions/, AGENTS.md)
2. Developer Documentation — Architecture and design decisions (docs/)
3. User Documentation — End-user guides (README, CHANGELOG)

AI Planning: Use .ai-scratch/ for temporary notes (never committed)

Rules:

• ❌ NEVER create random markdown files in code directories
• ❌ NEVER create documentation in .github/ unless it's a GitHub-specified file
• ✅ ALWAYS ask first before creating permanent documentation
• ✅ Prefer module docstrings over separate markdown files

Session and Context Management

Commit suggestions:

When a task completes and the developer moves to a new topic, suggest committing changes. Offer a commit message based on the work done.

Commit message format: Follow Conventional Commits specification

Common types: feat:, fix:, chore:, refactor:, docs:

Integration Architecture

This integration controls ActronAir Neo HVAC systems via cloud polling.

File Structure

custom_components/actronair_neo/
├── __init__.py          # Integration setup (async_setup_entry, async_unload_entry)
├── api.py               # Legacy API client (prefer api_wrapper.py for new code)
├── api_wrapper.py       # Primary API client (zone management, AC commands)
├── base_entity.py       # ActronAirNeoBaseEntity base class
├── binary_sensor.py     # Binary sensor platform
├── climate.py           # Main climate platform (HVAC control)
├── config_flow.py       # Configuration flow
├── const.py             # All constants (DOMAIN, modes, features)
├── coordinator.py       # DataUpdateCoordinator (ActronDataCoordinator)
├── diagnostics.py       # Diagnostics (redact sensitive data!)
├── exceptions.py        # Custom exception hierarchy
├── manifest.json        # Integration metadata
├── number.py            # Number platform (temperature setpoints, zone limits)
├── repairs.py           # Repair flows for issue recovery
├── sensor.py            # Sensor platform (temperature, humidity, status)
├── strings.json         # Translation source
├── switch.py            # Switch platform (zone toggles, continuous fan, etc.)
├── types.py             # TypedDict definitions for API responses
├── zone_presets.py      # Zone preset management
└── translations/
    └── en.json          # English translations

Data Flow (CRITICAL)

Entities → Coordinator → API Wrapper — Never skip layers

• Entities: Read coordinator.data only, never call API directly
• Coordinator: Calls api_wrapper.py, transforms data, handles errors
• API Wrapper: HTTP communication with ActronAir cloud, auth, command dispatch

Entity Platforms

Zone Architecture

ActronAir Neo uses a zone-based architecture:

• Master AC unit controls overall settings (mode, setpoint)
• Zones (numbered 0-N) can be individually enabled/disabled
• Zone presets in zone_presets.py allow saving/restoring zone configurations
• Zone data is fetched per-AC-serial via the coordinator

Exception Hierarchy

Defined in exceptions.py:

• ApiError — Base exception for all API errors
• AuthenticationError — Invalid or expired credentials
• ConfigurationError — Configuration issues
• ZoneError — Zone-related errors
• DeviceOfflineError — Device unreachable
• RateLimitError — API rate limiting

Coordinator mapping:

Code Style and Quality

Python: 4 spaces, 88 char lines, double quotes, full type hints, async for all I/O

YAML: 2 spaces, modern HA syntax

JSON: 2 spaces, no trailing commas, no comments

Validation: Run script/lint before committing (runs ruff format + ruff check --fix)

Linting command:

script/lint

For comprehensive standards, see:

• .github/instructions/python.instructions.md — Python patterns, imports, type hints
• .github/instructions/yaml.instructions.md — YAML structure
• .github/instructions/json.instructions.md — JSON formatting

Project-Specific Rules

Integration Identifiers

This integration uses the following identifiers consistently:

• Domain: actronair_neo
• Title: ActronAir Neo
• Class prefix: ActronAirNeo

When creating new files:

• Use the domain actronair_neo for all DOMAIN references
• Prefix integration-specific classes with ActronAirNeo
• Never hardcode different values

Key Constants (const.py)

Always import from const.py rather than hardcoding:

• DOMAIN — "actronair_neo"
• MANUFACTURER — "ActronAir"
• AC mode constants, feature flags, service names

Types (types.py)

• All API response structures use TypedDict from types.py
• Coordinator data structures should be typed
• Do NOT add new untyped dicts for API data — extend types.py

Diagnostics (diagnostics.py)

CRITICAL: Always use async_redact_data() to redact:

• API tokens / credentials
• User account identifiers
• Serial numbers (if considered sensitive)

See .github/instructions/diagnostics.instructions.md for patterns.

Config Flow

Located in config_flow.py (single file, not a package — current project structure).

• Supports user setup and options flow
• Unique ID must be the AC serial number or account identifier
• Never use IP addresses or hostnames as unique IDs

Coordinator

Located in coordinator.py as ActronDataCoordinator.

• Inherits from DataUpdateCoordinator
• Fetches and caches all AC data per update cycle
• Maps API exceptions to ConfigEntryAuthFailed / UpdateFailed
• Use async_config_entry_first_refresh() on setup

API Wrapper (api_wrapper.py)

Primary API client. Key responsibilities:

• Authentication with ActronAir cloud
• Fetching AC system status and zone data
• Sending commands (mode changes, setpoint, zone toggles)
• Session management (accept session from async_get_clientsession(hass))

Home Assistant Patterns

Config flow:

• See .github/instructions/config_flow.instructions.md for comprehensive patterns
• Always set unique_id, abort if already configured

Entities:

• Inherit from platform base + ActronAirNeoBaseEntity (from base_entity.py)
• Read from coordinator.data, never call API directly
• Use EntityDescription dataclasses for static entity metadata

Coordinator:

• Entities → Coordinator → API Wrapper (never skip layers)
• Raise ConfigEntryAuthFailed (triggers reauth) or UpdateFailed (retry)
• Use async_config_entry_first_refresh() for first update

Diagnostics:

• CRITICAL: Use async_redact_data() to remove sensitive data
• Redact: API keys, tokens, account IDs, serial numbers

Validation Scripts

Before committing, run:

script/lint      # Format + lint with ruff (auto-fix)
script/test      # Run unit tests
script/check     # Type-check + lint-check + spell-check (comprehensive)

Generate code that passes these checks on first run. Type hints, async patterns, and naming conventions should be correct before handing back to the developer.

Error Recovery Strategy

When validation fails:

1. First attempt — Fix the specific error reported by the tool
2. Second attempt — If it fails again, reconsider your approach
3. Third attempt — If still failing, ask for clarification
4. After 3 failed attempts — Stop and explain what you tried

Testing

Test structure:

• tests/ mirrors custom_components/actronair_neo/ modules
• Use fixtures for common setup (HA mock, coordinator, etc.)
• Mock external API calls — never make real network requests

Running tests:

script/test
script/test --cov
script/test --cov-html
script/test tests/test_coordinator.py -v

See .github/instructions/tests.instructions.md for comprehensive patterns.

Breaking Changes

Always warn the developer before making changes that:

• Change entity IDs or unique IDs (users' automations will break)
• Modify config entry data structure (existing installations will fail)
• Change state values or attribute format (dashboards and automations affected)
• Alter service call signatures (user scripts will break)
• Remove or rename config options (users must reconfigure)

Never do without explicit approval:

• Removing config options
• Changing service parameters or return values
• Renaming entities or changing device classes
• Changing unique_id generation logic

File Changes

Scope Management:

Single logical feature or fix:

• Implement completely even if it spans multiple files
• Example: New sensor needs entity class + platform init → implement all together

Multiple independent features:

• Implement one at a time
• Suggest committing before proceeding to the next

Large refactoring (>10 files or architectural changes):

• Propose a plan first before starting implementation
• Get explicit confirmation from developer

Important: Do NOT create or modify tests unless explicitly requested.

Translation strategy:

• Update strings.json and translations/en.json together
• NEVER update other language files automatically (use key references instead)
• Ask before creating new translation files

Research and Validation

When uncertain, consult official documentation:

• Home Assistant Developer Docs
• Developer Blog for recent changes
• Ruff Rules

Don't rely on assumptions — Home Assistant APIs evolve frequently.

Tool Parallelization

Safe to call in parallel:

• Multiple read_file operations
• file_search + read_file + grep_search (independent read-only operations)

Never call in parallel:

• Multiple run_in_terminal commands
• Multiple replace_string_in_file on the same file (use multi_replace_string_in_file)
• Multiple semantic_search calls

Additional Resources

• Home Assistant Developer Docs
• Integration Quality Scale
• Ruff Rules
• pytest Documentation
• See CONTRIBUTING.md for contribution guidelines