# Rules Engine

APScheduler-based automation rules engine for the home automation system.

## Features

- **APScheduler**: Background job scheduler for rule execution
- **Interval Jobs**: Periodic rule evaluation
- **Graceful Shutdown**: Proper signal handling (SIGINT, SIGTERM)
- **Logging**: Structured logging at INFO level

## Running

```bash
poetry run python -m apps.rules.main
```

## Architecture

The rules engine uses APScheduler's `BackgroundScheduler` to run automation rules on a schedule.

### Current Jobs

- **rule_tick**: Example job that runs every minute
  - Logs "Rule tick" message
  - Can be extended with actual rule logic

## Example Output

```
2025-10-31 13:05:46,865 - __main__ - INFO - Rules engine starting...
2025-10-31 13:05:46,868 - __main__ - INFO - Scheduler started with rule_tick job (every 1 minute)
2025-10-31 13:05:46,868 - __main__ - INFO - Rule tick
2025-10-31 13:06:46,874 - __main__ - INFO - Rule tick
2025-10-31 13:07:46,874 - __main__ - INFO - Rule tick
```

## Signal Handling

The application handles shutdown signals gracefully:

- **SIGINT** (Ctrl+C): Initiates graceful shutdown
- **SIGTERM**: Initiates graceful shutdown

On shutdown:
1. Stops accepting new jobs
2. Waits for running jobs to complete
3. Shuts down the scheduler
4. Exits cleanly

## Adding New Rules

To add a new rule, define a function and schedule it:

```python
def my_custom_rule() -> None:
    """Custom automation rule."""
    # Your rule logic here
    logger.info("Custom rule executed")

# In main():
scheduler.add_job(
    my_custom_rule,
    'interval',
    minutes=5,  # Run every 5 minutes
    id='custom_rule',
    name='My Custom Rule'
)
```

## Scheduler Triggers

APScheduler supports various trigger types:

- **interval**: Run at fixed intervals (e.g., every N minutes)
- **cron**: Run at specific times (e.g., daily at 8:00 AM)
- **date**: Run once at a specific datetime

Example with cron trigger:

```python
scheduler.add_job(
    morning_routine,
    'cron',
    hour=8,
    minute=0,
    id='morning',
    name='Morning Routine'
)
```

## Dependencies

- **APScheduler**: Advanced job scheduling

## Future Enhancements

- [ ] Load rules from configuration file
- [ ] MQTT integration for device state monitoring
- [ ] Rule conditions (if/then logic)
- [ ] Rule chaining and dependencies
- [ ] Web API for dynamic rule management
- [ ] Persistent job store (database)