"""
core/device/bottleneck.py

BottleneckAlert dataclass — describes a detected pipeline bottleneck.

Integration with InferencePipeline is deferred to a later phase.
This module only defines the data structure.
"""
from dataclasses import dataclass


@dataclass
class BottleneckAlert:
    """Describes a detected pipeline bottleneck in a single Stage.

    Attributes
    ----------
    stage_id:
        The pipeline Stage that is experiencing the bottleneck.
    queue_fill_rate:
        Input queue utilisation as a fraction in [0.0, 1.0].
    suggested_action:
        Human-readable suggestion (e.g. "Add more Dongles to this stage").
    severity:
        Either ``"warning"`` (fill_rate > 0.8) or ``"critical"``
        (fill_rate > 0.95).
    """

    stage_id: str
    queue_fill_rate: float
    suggested_action: str
    severity: str  # "warning" | "critical"