"""Trigger signal provider port protocol.

Define the interface for signal providers that detect meeting conditions.
"""

from __future__ import annotations

from typing import TYPE_CHECKING, Protocol

if TYPE_CHECKING:
    from noteflow.domain.triggers.entities import TriggerSignal, TriggerSource


class SignalProvider(Protocol):
    """Protocol for trigger signal providers.

    Signal providers detect specific conditions (audio activity, foreground app, etc.)
    and return weighted signals used in trigger evaluation.

    Each provider:
    - Has a specific source type
    - Has a maximum weight contribution
    - Can be enabled/disabled
    - Returns a signal when conditions are met, None otherwise
    """

    @property
    def source(self) -> TriggerSource:
        """Get the source type for this provider."""
        ...

    @property
    def max_weight(self) -> float:
        """Get the maximum weight this provider can contribute."""
        ...

    def get_signal(self) -> TriggerSignal | None:
        """Get current signal if conditions are met.

        Returns:
            TriggerSignal if provider conditions are satisfied, None otherwise.
        """
        ...

    def is_enabled(self) -> bool:
        """Check if this provider is enabled.

        Returns:
            True if provider is enabled and can produce signals.
        """
        ...
