Skip to content

Commit d7a5f28

Browse files
GuyKhGuyKh
committed
docs: add AGENTS.md for AI agent guidance
Add comprehensive AI agent instructions following Home Assistant custom component best practices. Includes project overview, code structure, development workflow, validation commands, and quality standards.
1 parent 8071c22 commit d7a5f28

File tree

1 file changed

+217
-0
lines changed

1 file changed

+217
-0
lines changed

‎AGENTS.md‎

Lines changed: 217 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,217 @@
1+
# AI Agent Instructions - IEC Custom Component
2+
3+
This document provides guidance for AI coding agents working on this Home Assistant custom integration project.
4+
5+
## Project Overview
6+
7+
This is a Home Assistant custom component for the Israel Electric Corporation (IEC) API. It provides sensors and binary sensors for monitoring electricity consumption, invoices, and meter readings.
8+
9+
**Integration details:**
10+
- **Domain:** `iec`
11+
- **Title:** IEC (Israel Electric Corporation)
12+
- **Repository:** GuyKh/iec-custom-component
13+
14+
**Key directories:**
15+
- `custom_components/iec/` - Main integration code
16+
- `config/` - Home Assistant configuration for local testing
17+
- `.github/workflows/` - CI/CD workflows
18+
19+
## Tech Stack
20+
21+
- **Python**: 3.10+
22+
- **Home Assistant**: 2025.1.4+
23+
- **iec-api**: 0.5.3 (Python client for IEC API)
24+
- **Linting**: ruff (with Home Assistant rules)
25+
- **Type Checking**: mypy
26+
27+
## Code Structure
28+
29+
```
30+
custom_components/iec/
31+
├── __init__.py # Integration entry point (async_setup_entry, async_unload_entry)
32+
├── const.py # Constants and DOMAIN definitions
33+
├── config_flow.py # UI configuration flow
34+
├── coordinator.py # DataUpdateCoordinator - main API logic
35+
├── commons.py # Shared utilities (timezone, helpers)
36+
├── sensor.py # Sensor platform
37+
├── binary_sensor.py # Binary sensor platform
38+
├── iec_entity.py # Base entity class
39+
└── services.yaml # Service definitions
40+
```
41+
42+
## Local Development
43+
44+
**Always use the project's scripts** — do NOT craft your own `hass`, `pip`, or similar commands. The scripts handle environment setup correctly.
45+
46+
**Setup:**
47+
```bash
48+
./scripts/setup # Install dependencies
49+
```
50+
51+
**Start Home Assistant:**
52+
```bash
53+
./scripts/develop # Start HA development environment
54+
```
55+
56+
**Debugging:**
57+
Enable debug logging in `config/configuration.yaml`:
58+
```yaml
59+
logger:
60+
default: info
61+
logs:
62+
custom_components.iec: debug
63+
iec_api: debug
64+
```
65+
66+
**Reading logs:**
67+
- Terminal where `./script/develop` runs
68+
- `config/home-assistant.log`
69+
70+
## Code Style
71+
72+
**Python:**
73+
- 4 spaces indentation
74+
- 120 character lines
75+
- Double quotes for strings
76+
- Full type hints (mypy strict)
77+
- Async for all I/O operations
78+
- Follow ruff rules from `.ruff.toml`
79+
80+
**Validation commands:**
81+
```bash
82+
./scripts/lint # Run ruff linter (auto-fixes where possible)
83+
./scripts/typecheck # Run mypy type checker
84+
```
85+
86+
## Key Patterns
87+
88+
### Integration Setup
89+
- Uses `ConfigEntry` for UI-based configuration
90+
- Supports multiple accounts (one entry per account)
91+
- Registers `PLATFORMS`: `sensor` and `binary_sensor`
92+
93+
### Coordinator Pattern
94+
- `IecApiCoordinator` extends `DataUpdateCoordinator`
95+
- Handles all API calls to IEC
96+
- Manages JWT tokens and authentication
97+
- Stores data in `hass.data[DOMAIN][entry.entry_id]`
98+
- Entities → Coordinator → API Client (never skip layers)
99+
- Raise `ConfigEntryAuthFailed` (triggers reauth) or `UpdateFailed` (retry)
100+
101+
### Entity Pattern
102+
- Base `IecEntity` class in `iec_entity.py`
103+
- Entities inherit from `CoordinatorEntity[IecApiCoordinator]`
104+
- Read from `coordinator.data`, never call API directly
105+
- Use `EntityDescription` dataclasses for static entity metadata
106+
107+
### Config Flow
108+
- Implement in `config_flow.py`
109+
- Support user setup, reauth
110+
- Always set `unique_id` for entries
111+
112+
## Project-Specific Rules
113+
114+
### IEC-Specific Identifiers
115+
- **Domain:** `iec`
116+
- **Class prefix:** `Iec`
117+
118+
### API Concepts
119+
- **Contracts**: Electrical contracts linked to user account
120+
- **Meters**: Physical meters associated with contracts
121+
- **Invoices**: Billing information (consumption, amount, payment status)
122+
- **Meter Readings**: Daily/hourly consumption data from smart meters
123+
- **Future Consumption**: Predicted consumption based on historical data
124+
125+
### Constants
126+
- All constants defined in `const.py`
127+
- Use `DOMAIN = "iec"` for all domain references
128+
- Prefix IEC-specific classes with `Iec`
129+
130+
### Data Storage Keys (from `const.py`)
131+
- `JWT_DICT_NAME` = "jwt"
132+
- `STATIC_DICT_NAME` = "statics"
133+
- `ATTRIBUTES_DICT_NAME` = "entity_attributes"
134+
- `ESTIMATED_BILL_DICT_NAME` = "estimated_bill"
135+
- `INVOICE_DICT_NAME` = "invoice"
136+
- `CONTRACT_DICT_NAME` = "contract"
137+
- `DAILY_READINGS_DICT_NAME` = "daily_readings"
138+
- `FUTURE_CONSUMPTIONS_DICT_NAME` = "future_consumption"
139+
140+
## Common Tasks
141+
142+
### Adding a New Sensor
143+
1. Add constants to `const.py` if needed
144+
2. Add sensor logic in `sensor.py`
145+
3. Follow existing sensor patterns (base entity → specific sensor)
146+
4. Add full type annotations (mypy strict)
147+
5. Use `EntityDescription` dataclass for static metadata
148+
149+
### Adding a New Binary Sensor
150+
1. Add constants to `const.py` if needed
151+
2. Add binary sensor logic in `binary_sensor.py`
152+
3. Follow existing patterns
153+
4. Add full type annotations
154+
155+
### API Changes
156+
When iec-api updates:
157+
1. Update version in `requirements.txt`
158+
2. Run type check to find breaking changes
159+
3. Update types as needed in `coordinator.py`
160+
161+
## Validation
162+
163+
**Before committing, run:**
164+
```bash
165+
./scripts/lint # Auto-format and fix linting issues
166+
./scripts/typecheck # Type checking
167+
```
168+
169+
**Configured tools:**
170+
- **Ruff** - Fast Python linter and formatter
171+
- **mypy** - Static type checker (strict mode)
172+
173+
### Error Recovery Strategy
174+
175+
**When first attempt validation fails:**
176+
1. **First attempt** - Fix the specific error reported by the tool
177+
2. **Second attempt** - If it fails again, reconsider your approach
178+
3. **Third attempt** - If still failing, stop and ask for clarification
179+
180+
**After ~10 file reads, you must either:**
181+
- Proceed with implementation based on available context
182+
- Ask the developer specific questions about what's unclear
183+
184+
## Testing
185+
186+
Tests are run via GitHub Actions workflows:
187+
- `.github/workflows/lint.yml` - Ruff linting
188+
- `.github/workflows/validate.yml` - Full validation (ruff + mypy)
189+
190+
## Breaking Changes
191+
192+
**Always warn the developer before making changes that:**
193+
- Change entity IDs or unique IDs (users' automations will break)
194+
- Modify config entry data structure (existing installations will fail)
195+
- Change state values or attributes format (dashboards affected)
196+
- Alter service call signatures (user scripts will break)
197+
- Remove or rename config options
198+
199+
**How to warn:**
200+
> "This change will modify the entity ID format. Existing users' automations and dashboards will break. Should I proceed, or would you prefer a migration path?"
201+
202+
## Quality Standards
203+
204+
**Follow Home Assistant patterns:**
205+
- Use type annotations (mypy strict)
206+
- Follow ruff rules
207+
- Add docstrings to public functions
208+
- Use Home Assistant constants from `homeassistant.const`
209+
- Implement proper error handling
210+
- Use `async_redact_data()` for sensitive data in diagnostics
211+
212+
## Additional Resources
213+
214+
- [Home Assistant Developer Docs](https://developers.home-assistant.io/)
215+
- [Integration Quality Scale](https://developers.home-assistant.io/docs/integration_quality_scale_index)
216+
- [Ruff Rules](https://docs.astral.sh/ruff/rules/)
217+
- [mypy Configuration](https://mypy.readthedocs.io/)

0 commit comments

Comments
 (0)