AI-Powered Home Automation Intelligence Platform
Transform your Home Assistant into an intelligent automation powerhouse with conversational AI, pattern detection, and advanced analytics.
Features · Quick Start · Architecture · Documentation · Tech Stack · Changelog · Docs Index
- What is HomeIQ?
- Features
- Quick Start
- Architecture
- Domain Groups
- Documentation
- Project Stats
- Roadmap
- Contributing
- License
HomeIQ is an AI-powered companion for Home Assistant that makes home automation accessible to everyone. Instead of writing complex YAML configurations, simply describe what you want in plain English.
Traditional Home Assistant:
alias: "Evening Routine"
trigger:
- platform: sun
event: sunset
action:
- service: light.turn_on
target:
entity_id: light.living_roomWith HomeIQ:
You: "Turn on living room lights at sunset"
HomeIQ: Created automation. Want to add conditions or additional actions?
| Feature | Description |
|---|---|
| Conversational AI | Create automations by chatting — no YAML required |
| Pattern Detection | AI discovers automation opportunities from your usage data |
| Advanced Analytics | Deep insights into device behavior, energy usage, and trends |
| Rich Integrations | Weather, energy pricing, air quality, sports, calendar, and more |
| Real-Time Dashboards | Interactive monitoring with live data visualization |
| Single-Home Optimized | Designed for Intel NUC deployment, not cloud-dependent |
- Natural Language — Create automations by describing what you want
- Pattern Mining — AI analyzes usage and suggests automations
- Automation Linter — Validate and auto-fix HA automations with 15+ quality rules (docs)
- Device Templates — Pre-built templates for common devices
- Proactive Suggestions — Context-aware recommendations based on weather, time, and events
- Health Monitoring — Battery levels, response times, maintenance alerts
- Smart Classification — Automatic device type detection (fridge, car, light, sensor)
- Setup Assistant — Step-by-step guides for new devices
- Power Analysis — Compare actual vs. expected power usage
- Live Dashboard — Monitor all devices and automations at localhost:3000
- Historical Data — Analyze patterns over days, weeks, or months
- Event Correlation — Understand how devices interact
- Performance Metrics — Track system health and response times
- Weather — Forecasts and conditions via OpenWeatherMap
- Energy Pricing — Real-time electricity costs
- Air Quality — AQI monitoring and alerts
- Sports — Live game tracking (NFL, NHL, and more)
- Carbon Intensity — Grid carbon footprint awareness
- Calendar — Event-triggered automations
- Home Assistant running on your local network
- Intel NUC (or similar) with 8GB+ RAM, 20GB+ disk space
- Docker and Docker Compose v2.0+
# Clone the repository
git clone https://github.com/wtthornton/HomeIQ.git
cd HomeIQ
# Copy and configure environment (Compose loads .env from the repo root)
cp infrastructure/env.example .env
# Edit .env with your settings:
# HA_HTTP_URL=http://YOUR_HA_IP:8123
# HA_WS_URL=ws://YOUR_HA_IP:8123/api/websocket
# HA_TOKEN=your-long-lived-access-token
# Start all services (by domain — recommended; groups by domain in Docker Desktop)
./scripts/start-stack.sh # Linux/Mac
.\scripts\start-stack.ps1 # Windows
# Optional: single merged Compose project (CI or flat Docker Desktop list — not recommended for daily use)
# docker compose --profile production up -d
# Verify deployment (run from repo root)
./scripts/verify-deployment.sh # Linux/Mac
.\scripts\verify-deployment.ps1 # Windows| Step | URL | Description |
|---|---|---|
| 1. Health Dashboard | localhost:3000 | View system health, service status, dependency graph |
| 2. AI Automation | localhost:3001 | Chat with AI to create automations |
| 3. API Explorer | localhost:8004/docs | Interactive Swagger API documentation |
| 4. Observability | localhost:8501 | Traces, performance metrics, live logs |
Deploy only the groups you need:
# Core only (data pipeline + dashboard)
docker compose -f domains/core-platform/compose.yml --profile production up -d
# Core + data collectors (include production-profile collectors: air-quality, carbon, etc.)
docker compose -f domains/core-platform/compose.yml \
-f domains/data-collectors/compose.yml --profile production up -d
# Full stack (~58 production-profile containers, grouped by domain in Docker Desktop)
./scripts/start-stack.sh # Linux/Mac
.\scripts\start-stack.ps1 # WindowsHomeIQ runs ~58 application containers (Docker Compose --profile production via start-stack) across 9 domain groups, with 62 service definitions in domain compose.yml files (the extra definitions are development / test profiles and one-shot jobs). Designed for single-home deployment on resource-constrained hardware.
┌─────────────────────────────────────────────────────────┐
│ HomeIQ Platform │
├─────────────────────────────────────────────────────────┤
│ Web Dashboards │
│ Health Dashboard (:3000) · AI Automation UI (:3001)│
│ Observability (:8501) · Jaeger Tracing (:16686) │
├─────────────────────────────────────────────────────────┤
│ AI / ML Services │
│ Conversational AI · Pattern Detection · NER │
│ Device Intelligence · Automation Mining · RAG │
├─────────────────────────────────────────────────────────┤
│ Core Platform │
│ websocket-ingestion → InfluxDB (time-series) │
│ data-api · admin-api · data-retention │
├─────────────────────────────────────────────────────────┤
│ Data Layer │
│ InfluxDB 2.8 (events, metrics) │
│ PostgreSQL 17 (metadata, schema-per-domain) │
├─────────────────────────────────────────────────────────┤
│ Monitoring (core-platform) │
│ Prometheus · Grafana · Alertmanager │
├─────────────────────────────────────────────────────────┤
│ Data collectors & enrichment │
│ Weather · Energy · Air Quality · Sports · Calendar · Zeek │
└─────────────────────────────────────────────────────────┘
▲
┌────────┴────────┐
│ Home Assistant │
│ (Your Home) │
└─────────────────┘
Data Flow: Home Assistant → websocket-ingestion → InfluxDB (direct writes, inline normalization) → data-api (query layer)
- Service Groups — The 9-domain deployment structure
- Service Tiers — Complete criticality classification
- Event Flow — Event processing and data flow
- Database Schema — InfluxDB + PostgreSQL schema reference
| # | Domain | Services (production profile) | Purpose |
|---|---|---|---|
| 1 | core-platform | 11 | Data backbone — InfluxDB, PostgreSQL, data-api, websocket-ingestion, admin-api, health-dashboard, data-retention, Prometheus, Grafana, Alertmanager, postgres-exporter |
| 2 | data-collectors | 10 | Stateless fetchers + network — weather, smart-meter, sports, air-quality, carbon-intensity, electricity-pricing, calendar, log-aggregator, zeek, zeek-network-service |
| 3 | ml-engine | 8 | ML inference and training — OpenVINO, ML, NER, OpenAI, RAG, ai-core, ai-training, device-intelligence (model-prep is development one-shot) |
| 4 | automation-core | 8 | Automation engine — ha-ai-agent, ai-automation, query, YAML validation, linter, code-executor, trace service, ha-device-control |
| 5 | blueprints | 4 | Blueprint discovery, indexing, ML recommendations |
| 6 | energy-analytics | 3 | Energy correlator, forecasting, proactive agent |
| 7 | device-management | 8 | Device health, setup, classification, activity recognition, ha-setup |
| 8 | pattern-analysis | 2 | Behavioral patterns, api-automation-edge |
| 9 | frontends | 4 | Jaeger, observability dashboard, AI automation UI, voice-gateway (health-dashboard lives in core-platform) |
Each domain group has its own compose.yml under domains/<group>/ and can be deployed independently. See Service Groups Architecture for dependency graph and deployment commands.
| Document | Description |
|---|---|
| Deployment Runbook | Step-by-step deployment guide with service verification |
| Deployment Pipeline | CI/CD pipeline documentation |
| API Reference | Complete REST API reference with all endpoints and ports |
| Document | Description |
|---|---|
| Service Groups | 9-domain group structure and deployment topology |
| Database Schema | InfluxDB + PostgreSQL schema reference |
| Event Flow | Event processing pipeline and data flow |
| Quick Reference | Service patterns and architecture overview |
| Document | Description |
|---|---|
| PostgreSQL Runbook | Database operations, maintenance, and troubleshooting |
| Disaster Recovery | Backup, restore, and recovery procedures |
| Monitoring Setup | Prometheus + Grafana configuration |
| Service Health Checks | Health endpoint patterns and verification |
| Document | Description |
|---|---|
| Tech Stack | Complete technology reference with versions |
| Automation Linter | YAML linting and validation service |
| Linter Rules | Complete rules catalog |
| Changelog | Version history |
| Document | Description |
|---|---|
| Open Epics Index | All open epics and stories with priorities |
| Rebuild Status | Phase completion tracker |
| Phase 5 Deployment | Production deployment plan |
Documentation index: All doc paths and correct references → docs/README.md
| Metric | Value |
|---|---|
| Services | ~58 containers with start-stack + --profile production; 62 Compose definitions (incl. test/dev) |
| Target Hardware | Intel NUC (i3/i5, 8–16 GB RAM) |
| Memory Footprint | ~8–10 GB (optimized) |
| Optimized For | Single home, 50–100 devices |
| Backend | Python 3.12, FastAPI 0.115–0.124, Pydantic 2.x |
| Frontend | React 18.3, TypeScript 5.9, Vite 6.4, Tailwind CSS 3.4 |
| AI/ML | Sentence-Transformers 3.3, OpenAI GPT-4o-mini, scikit-learn |
| Databases | InfluxDB 2.8.x (time-series), PostgreSQL 17 (metadata) |
| Observability | OpenTelemetry, Jaeger 1.75, Prometheus, Grafana |
| Tests | 704+ tests, Playwright E2E, pytest-asyncio |
- Conversational AI automation (NL to YAML)
- Pattern detection and proactive suggestions
- Device health monitoring and classification
- Multi-source data enrichment (7 providers)
- PostgreSQL migration — sole database (Epic 0 complete)
- Library upgrades — Phases 1–2 complete
- Frontend redesign — teal palette, sidebar nav, accessibility
- Agent evaluation framework with observability
- Cross-group resilience (circuit breakers, health aggregation)
- Security hardening (SQL injection, timing attacks, CORS)
- Frontend security hardening (Epic 1 — Sprint 1)
- Observability dashboard fixes (Epic 4)
- Health dashboard quality improvements (Epic 2)
- Phase 3 ML library upgrades (NumPy 2.x, Pandas 3.0)
- Production deployment (Phase 5)
- Frontend framework upgrades (React 19, Vite 7, Tailwind 4)
- Mobile app integration
- Voice assistant support
- Multi-language support
See OPEN-EPICS-INDEX.md for the full backlog and sprint plan.
Contributions are welcome! See CONTRIBUTING.md for the full guide, including:
- Development setup and guidelines
- Quality gate expectations — every PR is automatically checked by the TAPPS quality pipeline
- How to run quality checks locally before pushing
- Pull request process
# Fork the repo, then:
git clone https://github.com/YOUR_USERNAME/HomeIQ.git
cd HomeIQ
git checkout -b feature/your-feature-name
# Make changes, run quality checks, then push
pip install tapps-mcp ruff
tapps-mcp validate-changed --preset standard
git commit -m "feat: add your feature description"
git push origin feature/your-feature-name- Bug Reports — GitHub Issues
- Discussions — GitHub Discussions
- Documentation — docs/
This project is licensed under the ISC License — see the LICENSE file for details.
- Home Assistant — The home automation platform
- FastAPI — Modern Python web framework
- InfluxDB — Time-series database
- PostgreSQL — Relational database
- React — UI library
Made with care for the Home Assistant community