First commit

.github/copilot-instructions.md

@@ -0,0 +1,82 @@
+# Copilot / AI Agent Instructions for system2mqtt
+
+Short, actionable guidance so an AI coding agent can be immediately productive.
+
+1. Purpose
+- This repo collects host metrics and publishes them to Home Assistant over MQTT.
+- Main entry point: `system2mqtt` console script (defined in `setup.py`).
+
+2. How to run (development)
+- Create a venv and install deps:
+  ```bash
+  python3 -m venv .venv
+  source .venv/bin/activate
+  pip install -r requirements.txt
+  pip install -e .
+  ```
+- Run the service with the provided entry point:
+  ```bash
+  system2mqtt
+  ```
+- Environment override: set `SYSTEM2MQTT_CONFIG` to point to a `config.yaml` path.
+
+3. Big-picture architecture
+- `system2mqtt.main` (console entry) loads configuration, connects to MQTT, discovers collector modules under `src/system2mqtt/collectors/`, and loops to:
+  - call each collector's `collect_metrics()`
+  - publish Home Assistant discovery payloads and state/attributes topics
+  - publish availability to `system2mqtt/{HOSTNAME}/status`
+- Collectors are pure Python modules (examples: `collectors/system_metrics.py`, `collectors/cpu_temperature.py`, `collectors/zfs_pools.py`). The main program imports them dynamically via `collectors.<name>` and expects a `collect_metrics()` function.
+
+4. Collector conventions (exact, follow these)
+- Each collector should expose `collect_metrics() -> Dict` which returns a dict with an `entities` list.
+- Each entity must include at least: `sensor_id`, `name`, `value`, `state_class`, `unit_of_measurement`, `device_class`, and `attributes`.
+- Optional: module-level `DEFAULT_INTERVAL` can be present (collectors include this today), but note: current `main` does not use per-collector intervals (see "Notable quirks").
+- Example entity (from `system_metrics.py`):
+  ```py
+  {
+    "sensor_id": "cpu_usage",
+    "name": "CPU Usage",
+    "value": "12.3",
+    "state_class": "measurement",
+    "unit_of_measurement": "%",
+    "device_class": "power_factor",
+    "attributes": {"friendly_name": "CPU Usage"}
+  }
+  ```
+
+5. Configuration and secrets
+- Default config path: `~/.config/system2mqtt/config.yaml` (created from `config.yaml.example` on first run).
+- `SYSTEM2MQTT_CONFIG` env var can override the config file location.
+- Required config keys under `mqtt`: `host`, `port`, `username`, `password`, `client_id`, `discovery_prefix`.
+
+6. MQTT topics & discovery (concrete examples)
+- Discovery topic format published by `main`:
+  `{discovery_prefix}/sensor/system2mqtt_{HOSTNAME}_{sensor_id}/config`
+- State topic format: `system2mqtt/{HOSTNAME}/{sensor_id}/state`
+- Attributes topic: `system2mqtt/{HOSTNAME}/{sensor_id}/attributes` (JSON)
+- Availability: `system2mqtt/{HOSTNAME}/status` with `online` / `offline` payloads (retained)
+
+7. Integration points & dependencies
+- MQTT client: `paho-mqtt` (callback handlers in `main.py`).
+- System metrics: `psutil` used by `collectors/system_metrics.py`.
+- ZFS collectors call `zpool` binaries via `subprocess` (requires ZFS tools present on host).
+
+8. Notable quirks & places to be careful
+- The README mentions per-collector update intervals, and collector modules define `DEFAULT_INTERVAL`, but `main.py` currently uses a fixed `time.sleep(60)` and does not schedule collectors individually. If changing scheduling, update `main.py` to read collector `DEFAULT_INTERVAL` or config `collectors.intervals`.
+- `main.py` lists collectors from the relative `collectors` directory using `os.listdir('collectors')`. For correct imports:
+  - Run from package-installed environment (`pip install -e .`) and call `system2mqtt` (recommended), or
+  - Ensure working directory / `PYTHONPATH` is set so `collectors` import works.
+- On first run the code copies `config.yaml.example` to the user config dir and exits — tests or CI should populate a config before invoking `system2mqtt`.
+
+9. Suggested tasks for AI agents (concrete, small changes)
+- Implement per-collector scheduling using `DEFAULT_INTERVAL` or `config['collectors']['intervals']`.
+- Add unit tests around collector `collect_metrics()` return schema (validate required keys).
+- Improve error handling around dynamic imports (log which path was attempted).
+
+10. Where to look in the code
+- Entry point & runtime: `src/system2mqtt/main.py`
+- Collector examples: `src/system2mqtt/collectors/*.py` (`system_metrics.py`, `cpu_temperature.py`, `zfs_pools.py`)
+- Example config: `config.yaml.example`
+- Packaging / console script: `setup.py` (entry point `system2mqtt`)
+
+If anything here is unclear or you want the instructions to emphasize other areas (tests, CI, packaging), tell me which part to expand or correct.