ML-based room occupancy prediction for Home Assistant integration.
This system predicts room occupancy and vacancy using machine learning models trained on sensor data from Home Assistant. It provides predictions for:
- Occupancy Predictions: Will a room be occupied in 15 minutes (cooling) or 2 hours (heating)?
- Vacancy Predictions: When will an occupied room become vacant?
- Python 3.12+
- Poetry
- Docker and Docker Compose
- Home Assistant with FP2 sensors
- Clone the repository:
git clone <repository-url>
cd occupancy-predictor- Install dependencies:
make dev- Copy and configure environment variables:
cp .env.example .env
# Edit .env with your configuration- Start infrastructure services:
make docker-upRun formatting and linting:
make format
make lint
make type-checkRun tests:
make testRun all checks:
make allThe system requires configuration for:
- PostgreSQL: Database for storing sensor readings and predictions
- Redis: Caching layer for real-time data
- Home Assistant: Source of sensor data via WebSocket and REST API
- Prometheus: Metrics collection (connects to external Grafana)
The docker-compose.yml includes:
- PostgreSQL 16: Primary database
- Redis 7: Caching and session storage
- Prometheus: Metrics collection
Note: Grafana runs on a separate external instance.
The system is configured for these rooms:
- bedroom
- bathroom
- small_bathroom (shower)
- office
- living_kitchen
- guest_bedroom
- Make changes to code
- Run
make allto validate - Commit changes (pre-commit hooks will run)
- Submit pull request
- FastAPI: REST API for predictions
- SQLAlchemy: Database ORM with async support
- LightGBM: Gradient boosting ML models
- Prometheus: Metrics and monitoring
- Home Assistant: Data source and automation target
Please ensure all code follows the established patterns:
- Type hints on all functions
- Async/await for I/O operations
- Structured logging with context
- Comprehensive error handling
- 80%+ test coverage
MIT License