From c661658a12cfa7e6d94494ed1395e79c2e171c4e Mon Sep 17 00:00:00 2001
From: Brad Stein <Brad.Stein@gmail.com>
Date: Tue, 16 Dec 2025 01:45:04 -0300
Subject: [PATCH] Add AC Infinity ingestion plan

---
 .gitignore |  3 +++
 NOTES.md   | 39 +++++++++++++++++++++++++++++++++++++++
 2 files changed, 42 insertions(+)
 create mode 100644 NOTES.md

diff --git a/.gitignore b/.gitignore
index 88b0632..3f1a193 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,2 +1,5 @@
 *.md
 !README.md
+!AGENTS.md
+!**/NOTES.md
+!NOTES.md
diff --git a/NOTES.md b/NOTES.md
new file mode 100644
index 0000000..c409499
--- /dev/null
+++ b/NOTES.md
@@ -0,0 +1,39 @@
+AC Infinity metrics → Grafana plan
+==================================
+
+Goal: expose tent ambient temperature and fan speeds (inlet indoor/outdoor, outlet, internal) on metrics.bstein.dev overview. Keep the footprint minimal; avoid full Home Assistant if possible.
+
+Option A (slim exporter; recommended)
+- Use the community AC Infinity Python client (from the Home Assistant custom component) wrapped in a tiny Prometheus exporter.
+- Flow:
+  1) Deploy a `Deployment` in `monitoring` (e.g., `acinfinity-exporter`) that:
+     - Reads AC Infinity cloud creds from a `Secret` (populated via Vault).
+     - Polls the AC Infinity cloud API on an interval (e.g., 30–60s) using the client to fetch current sensor state.
+     - Exposes `/metrics` with gauges: `acinfinity_temp_c`, `acinfinity_humidity_percent`, `acinfinity_fan_speed_percent{fan="inlet_indoor|inlet_outdoor|outlet|internal"}`, `acinfinity_mode`, `acinfinity_alarm`, etc.
+  2) Add a `Service` + `ServiceMonitor` to scrape the exporter. Metric relabel to friendly names if needed.
+  3) Update `scripts/dashboards_render_atlas.py` to add:
+     - Ambient temp gauge (°C/°F) on Overview.
+     - Fan speed gauges (3–4 panels) for inlet/outlet/internal.
+  4) Regenerate dashboards (`python3 scripts/dashboards_render_atlas.py --build`), commit, push, reconcile `monitoring`.
+- Pros: minimal footprint, no HA. Cons: need to vendor the client library and keep it in sync if AC Infinity changes their API.
+
+Option B (minimal Home Assistant)
+- Run a stripped-down Home Assistant in `monitoring` with only the AC Infinity custom integration and Prometheus exporter enabled.
+- Flow:
+  1) HA `Deployment` + PVC or emptyDir for config; `Secret` for AC Infinity creds; HA API password in Secret.
+  2) Prometheus scrapes `http://ha-acinfinity:8123/api/prometheus?api_password=...` via `ServiceMonitor`.
+  3) Same dashboard steps as above after metric relabeling to `acinfinity_*`.
+- Pros: reuse maintained HA integration. Cons: heavier than exporter, HA maintenance overhead.
+
+Secrets and ops
+- Store AC Infinity username/password in Vault; template into a Secret consumed by the exporter/HA.
+- Network: allow outbound HTTPS to AC Infinity cloud from the Pod.
+- Interval: 30–60s polling is usually enough; avoid hammering the API.
+
+Implementation sketch (Option A)
+- New image `monitoring/acinfinity-exporter` (Python + prometheus_client + AC Infinity client).
+- Deployment (namespace `monitoring`): env AC_INFINITY_USER/PASS, POLL_INTERVAL, LISTEN_ADDR.
+- Service: `port: 9100` (or similar).
+- ServiceMonitor: scrape `/metrics` every 30–60s, metricRelabel to normalize names/labels.
+- Dashboard panels: add to Overview top/mid rows; regenerate JSONs; push; reconcile `monitoring`.
+