Initial Home Assistant observer

README.md

@@ -0,0 +1,136 @@
+# Home Assistant Observer
+
+Cron-friendly Home Assistant observer:
+
+- every 30 minutes: collect compact Home Assistant snapshots into `./data`
+- every day at 05:00: send the last day of snapshots to AI
+- publish a funny local webpage at `./web/index.html`
+- save Markdown AI reports in `./reports`
+
+## Setup
+
+```bash
+cd /home/hbrain/ha
+python3 -m venv .venv
+. .venv/bin/activate
+pip install -r requirements.txt
+cp .env.example .env
+chmod 600 .env
+chmod +x run_ha_observer.sh ha_observer.py install_cron.sh
+```
+
+Edit `.env` and set:
+
+```bash
+HA_URL="http://homeassistant.local:8123"
+HA_TOKEN="your_long_lived_home_assistant_token"
+```
+
+Create the token in Home Assistant:
+
+```text
+Profile → Security → Long-lived access tokens
+```
+
+## AI mode for the 05:00 report
+
+Local Ollama is recommended for privacy:
+
+```bash
+LLM_MODE="ollama"
+OLLAMA_MODEL="llama3.1"
+```
+
+OpenAI cloud API:
+
+```bash
+LLM_MODE="openai"
+OPENAI_API_KEY="..."
+OPENAI_MODEL="gpt-4o-mini"
+```
+
+No AI, but still publish a placeholder page:
+
+```bash
+LLM_MODE="none"
+```
+
+## Extra LLM instructions
+
+Edit this file to change how the 05:00 AI analysis behaves:
+
+```text
+/home/hbrain/ha/llm_instructions.md
+```
+
+For example, add specific questions, preferred tone, things to ignore, or extra privacy/security concerns. The file is automatically appended to the AI prompt during `analyze`.
+
+You can change the path in `.env`:
+
+```bash
+PROMPT_FILE="./llm_instructions.md"
+```
+
+## Test manually
+
+Collect one snapshot:
+
+```bash
+./run_ha_observer.sh collect
+```
+
+Run the 05:00-style analysis/publishing step:
+
+```bash
+./run_ha_observer.sh analyze
+```
+
+Open the page:
+
+```bash
+xdg-open /home/hbrain/ha/web/index.html
+```
+
+Or serve it locally:
+
+```bash
+cd /home/hbrain/ha/web
+python3 -m http.server 8088
+```
+
+Then browse to:
+
+```text
+http://localhost:8088/
+```
+
+## Install cron jobs
+
+This installs exactly these jobs:
+
+- `*/30 * * * *` collect snapshots every 30 minutes
+- `0 5 * * *` analyze with AI and publish the funny local webpage
+
+```bash
+./install_cron.sh
+```
+
+Manual crontab equivalent:
+
+```cron
+*/30 * * * * /home/hbrain/ha/run_ha_observer.sh collect >> /home/hbrain/ha/cron.log 2>&1
+0 5 * * * /home/hbrain/ha/run_ha_observer.sh analyze >> /home/hbrain/ha/cron.log 2>&1
+```
+
+## Output locations
+
+```text
+/home/hbrain/ha/data/       30-minute JSON snapshots
+/home/hbrain/ha/reports/    daily Markdown AI reports
+/home/hbrain/ha/web/        local funny webpage, index.html
+/home/hbrain/ha/cron.log    cron logs
+```
+
+## Privacy notes
+
+Home Assistant data can reveal sleep schedule, occupancy, work patterns, visitors, location habits, and security weaknesses. Prefer `LLM_MODE=ollama` to keep analysis local. Use `EXCLUDED_ENTITIES` in `.env` to omit sensitive/noisy entities.