Hankanman Area-Occupancy-Detection .cursorrules file for Python (stars: 57)

# Project Instructions

Use this document as a guideline to build the Home Assistant integration for Area Occupancy Detection. All modifications should align with the Integration Goal

## Overview

This integration provides intelligent room occupancy detection by combining multiple sensor inputs using Bayesian probability calculations. It detects occupancy more accurately than single motion sensors by considering various environmental factors and device states.

## Integration Goal

Take the input entities from the configuration (motion/occupancy sensors, appliances/other devices, media devices, lights, doors, windows and environmental factors) as defined in the configuration flow, figuring out their priors based on a strong indicator such as an existing motion or occupancy sensor, so for example we should look at the history of say a media device and determine how much the "playing" or "paused" state coincides with a valid occupancy sensor being "on" over the configure history period for example the last 7 days, it should interrogate the recorder or statistics integration to do this.

There are constants stored in probabilities.py as defaults, they should be overridden by the "true" data found in the coordinator for a prob_given_false, prob_given_true and prior_probability. These values should then be passed into a composite bayesian calculation alongside the given sensors current state to determine the current probability of a given area being occupied based upon the input sensors of from the configuration

The Occupancy Probability sensor is the overall bayesian probability calculation shown as a percentage.

The Occupancy Status sensor is a binary sensor that is on if the Occupancy Probability is above the threshold and off if it is below the threshold.

The Occupancy Prior sensor is the prior probability of the area being occupied based upon the input sensors from the configuration.

The individual prior sensors are the prior probabilities of the input sensors from the configuration for each given category (motion, media, appliances, doors, windows, lights and environmental factors).


## Tech Stack

- Language: Python
- Framework: Home Assistant Core
- Testing: Pytest
- Linting: Pylint, Flake8

## Project Structure

- `custom_components/area_occupancy` - Main integration directory
  - `__init__.py` - Integration setup
  - `binary_sensor.py` - Binary sensor entity definitions
  - `calculate_prob.py` - Probability calculations
  - `calculate_prior.py` - Prior probability calculations
  - `config_flow.py` - Configuration flow for the integration
  - `const.py` - Constants used across the integration
  - `coordinator.py` - Coordinator for the integration
  - `manifest.json` - Integration metadata
  - `probabilities.py` - Probability constants provider
  - `sensor.py` - Sensor entity definitions
  - `service.py` - Service creation and management
  - `strings.json` - Integration strings
  - `types.py` - Type definitions
  - `services.yaml` - Service definitions
  - `translations/` - Localized strings
- `tests/` - Unit tests for the integration

## Rules

Follow these rules strictly to ensure high-quality development.

### General Rules

- Adhere to Home Assistant’s [developer documentation](https://developers.home-assistant.io/).
- Use built-in Home Assistant utilities and constants where applicable, such as `homeassistant.helpers.entity`, `homeassistant.const`, etc.
- Avoid custom implementations of functionality already available in Home Assistant.
- Maintain consistency with Home Assistant patterns and practices.
- Use snake_case for all file names and variables.
- Follow PEP8 standards.
- Use `asyncio.Lock` for state locking.
- All constants should be defined in `const.py`.
- All types should be defined in `types.py`.
- All configuration should be defined in `config_flow.py`.
- All services should be defined in `services.py`.
- All sensors should be defined in `sensor.py`.
- All binary sensors should be defined in `binary_sensor.py`.
- All calculations should be defined in `calculate_prob.py` and `calculate_prior.py`.
- All probabilities should be defined in `probabilities.py`.
- All exceptions should include the stack trace.
- NEVER truncate your code, always use the full codebase to complete the task.
- NEVER use placeholders like "... existing logic ..." in your code, always implement the full logic.
- NEVER use general exceptions like `Exception` or `BaseException` in your code, always use specific exceptions.

### Environment Rules

- Ensure `requirements.txt` includes all necessary Python dependencies.
- Update `manifest.json` with correct metadata, versioning, and dependencies.
- Use Home Assistant’s core logging facilities for debug and error logs.
- Avoid excessive use of `try/except` blocks; handle exceptions with specific, targeted error handling.
- Use f-strings for formatting log messages for consistency.

### Linting Rules

- Run `pylint` and `flake8` before committing code.
- Address all warnings and errors reported by the linters.

### Testing Rules

- Write unit tests using `pytest`.
- Cover all entities, services, and configuration flows with appropriate test cases.
- Use the Home Assistant test harness for mocking core components.
- Achieve at least 90% test coverage.
- Test edge cases such as sensor unavailability, invalid configurations, and extreme input values.
- Structure test cases to include setup, execution, and verification phases clearly.

### Component Rules

#### Sensor Entities

- Inherit from `homeassistant.helpers.entity.SensorEntity`.
- Use descriptive unique IDs for each sensor.
- Implement `device_class`, `unit_of_measurement`, and `state_class` where applicable.
- Include fallback values for attributes in case of missing data.

#### Binary Sensor Entities

- Extend `BinarySensorEntity` and provide specific logic for state determination.
- Handle decayed states explicitly with time-based thresholds.
- Use Home Assistant-provided constants for binary sensor states and attributes.

#### Configuration Flow

- Use `homeassistant.config_entries.ConfigFlow` for user setup.
- Validate user inputs during configuration using Voluptuous schemas.
- Provide user-friendly error messages and recovery steps.

#### Services

- Define services in `services.yaml`.
- Use descriptive names and clear schemas for service parameters.
- Ensure services are idempotent and handle invalid states gracefully.

### Logging Rules

- Use Home Assistant’s `logging.getLogger` for logging.
- Include relevant context in log messages without exposing sensitive information.
- Use appropriate log levels: `DEBUG` for development, `INFO` for general logs, `WARNING` for recoverable issues, and `ERROR` for critical failures.
- Log exceptions with `exc_info=True` for stack traces only when debugging.

### Documentation Rules

- Provide a README with installation instructions, feature explanations, and usage examples.
- Add comments to explain non-trivial code sections.
- Use docstrings for all public methods and classes.
- Document the Bayesian calculation logic explicitly in the code.

By adhering to these guidelines, you will create a robust, maintainable, and high-quality integration for Home Assistant.