# Home Assistant Data Analysis

Data analysis notebooks for investigating power consumption and other smart home metrics collected by Home Assistant.

## Project Structure

```bash
.
├── .gitea/
│   └── workflows/
│       └── setup_database.yml    # CI workflow to setup PostgreSQL database
├── notebooks/
│   └── boiler_warning.ipynb      # Power consumption analysis notebook
├── utils/
│   ├── __init__.py
│   └── db_connection.py          # Shared database connection utilities
├── .env.example                   # Example environment variables
├── .gitignore
├── pyproject.toml                # Project dependencies and configuration
└── README.md
```

## Setup

### 1. Install UV (Python Package Manager)

```bash
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Or via Homebrew
brew install uv
```

### 2. Create Virtual Environment and Install Dependencies

```bash
# Create and activate virtual environment with UV
uv venv
source .venv/bin/activate  # On macOS/Linux

# Install dependencies
uv pip install -e .
```

### 3. Configure Database Connection

```bash
# Copy example environment file
cp .env.example .env

# Edit .env with your PostgreSQL credentials
nano .env  # or use your preferred editor
```

### 4. Run Jupyter Notebooks

```bash
# Start Jupyter Lab
jupyter lab

# Or Jupyter Notebook
jupyter notebook
```

## Database Setup

The repository includes a CI workflow (`.gitea/workflows/setup_database.yml`) that can be manually triggered to initialize the PostgreSQL database. Ensure the following secrets are configured in your Gitea repository:

- `POSTGRES_HOST`
- `POSTGRES_PORT`
- `POSTGRES_ROOT_PASSWORD`
- `DB_NAME`
- `DB_USER`
- `DB_PASSWORD`

## Notebooks

### Current Notebooks

- **boiler_warning.ipynb**: Analysis of power consumption data from Home Assistant

### Adding New Notebooks

1. Create new notebook in the `notebooks/` directory
2. Use descriptive names (e.g., `temperature_trends.ipynb`, `energy_efficiency.ipynb`)
3. Import shared utilities: `from utils import get_db_connection, get_db_engine`

## Shared Utilities

The `utils/` module provides common functions for database connections:

```python
from utils import get_db_connection, get_db_engine

# Using psycopg2 (for raw SQL)
conn = get_db_connection()
cursor = conn.cursor()
cursor.execute("SELECT * FROM states LIMIT 10")

# Using SQLAlchemy (for pandas integration)
engine = get_db_engine()
import pandas as pd
df = pd.read_sql("SELECT * FROM states LIMIT 10", engine)
```

## Development

### Optional Development Tools

Install development dependencies for code formatting and linting:

```bash
uv pip install -e ".[dev]"
```

Format code with Black:

```bash
black utils/
```

Lint code with Ruff:

```bash
ruff check utils/
```

## Contributing

When adding new analysis notebooks:

1. Document the purpose and findings in the notebook
2. Add any new dependencies to `pyproject.toml`
3. Update this README if adding significant new functionality