## PRD: Enhanced Downscaling Logic with Hysteresis

This PRD focuses on refining the downscaling process within AIVA by introducing hysteresis. This will prevent frequent upscaling and downscaling oscillations due to minor fluctuations in resource utilization.

### GPM-056: Implement Hysteresis Threshold for Downscaling

**Goal:** Introduce a separate, lower threshold for downscaling compared to the upscaling threshold.
**Acceptance Criteria:**
- A new configuration parameter `downscale_hysteresis_percent` is added to the AIVA configuration.
- The downscaling logic uses the `downscale_hysteresis_percent` to calculate the actual downscaling threshold.
- The system only initiates downscaling when resource utilization is below this new, lower threshold.
**Files:** `config.py`, `autoscaler.py`
**Spawns:** Explore dynamically adjusting the hysteresis threshold based on workload patterns.

### GPM-057: Modify Downscale Timer to Respect Hysteresis

**Goal:** Ensure the downscale timer only starts when resource utilization falls below the hysteresis threshold.
**Acceptance Criteria:**
- The downscale timer only starts counting down when resource utilization is below the `downscale_hysteresis_percent` threshold.
- If resource utilization rises above the `downscale_hysteresis_percent` threshold, the timer is reset.
**Files:** `autoscaler.py`
**Spawns:** Investigate different timer reset strategies (e.g., immediate reset vs. gradual decrease).

### GPM-058: Log Resource Utilization and Downscaling Decisions

**Goal:** Improve observability by logging resource utilization and downscaling decisions, including the hysteresis threshold used.
**Acceptance Criteria:**
- Resource utilization is logged at regular intervals, including the current value and the upscaling/downscaling thresholds.
- Each downscaling decision (initiation, cancellation, execution) is logged, including the resource utilization at the time of the decision and the hysteresis threshold used.
**Files:** `logger.py`, `autoscaler.py`
**Spawns:** Implement visualizations based on the logged data to facilitate performance analysis and tuning.

### GPM-059: Unit Tests for Hysteresis-Based Downscaling

**Goal:** Create unit tests to verify the correctness of the hysteresis-based downscaling logic.
**Acceptance Criteria:**
- Unit tests cover scenarios where resource utilization fluctuates around both the upscaling and downscaling thresholds.
- Unit tests verify that downscaling only occurs when resource utilization is below the hysteresis threshold for the required time.
- Unit tests confirm the timer resets correctly when resource utilization exceeds the hysteresis threshold.
**Files:** `tests/test_autoscaler.py`
**Spawns:** Create integration tests to evaluate the hysteresis mechanism in a more realistic environment.

### GPM-060: Configuration Documentation for Hysteresis Settings

**Goal:** Update the AIVA configuration documentation to explain the new `downscale_hysteresis_percent` setting.
**Acceptance Criteria:**
- The documentation clearly explains the purpose of the `downscale_hysteresis_percent` setting.
- The documentation provides guidance on choosing an appropriate value for the setting.
- The documentation includes examples of how the setting affects downscaling behavior.
**Files:** `docs/configuration.md`
**Spawns:** Develop a dynamic advisor to suggest optimal hysteresis values based on historical workload data.

### GPM-061: Implement a Minimum Resource Limit

**Goal:** Prevent downscaling from reducing resources to a level that could cause service disruptions.
**Acceptance Criteria:**
- A new configuration parameter `minimum_resource_units` is added to the AIVA configuration, representing the absolute minimum resource units AIVA can scale down to.
- The downscaling logic ensures that the resource allocation never drops below this specified minimum, regardless of resource utilization.
**Files:** `config.py`, `autoscaler.py`
**Spawns:** Implement alert mechanisms to notify administrators if resource requests are consistently hitting the minimum resource limit.
