"""GibberishScanner for meshulash-guard SDK.

Detects random or adversarial noise in user input via character and bigram
frequency analysis on the server side. Supports Hebrew and English. The
scanner is a pure config serializer: no detection logic runs in the SDK.
"""

from __future__ import annotations

from ..enums import Action
from .base import BaseScanner


class GibberishScanner(BaseScanner):
    """Scanner for gibberish and adversarial noise detection.

    Uses character and bigram analysis (server-side) to detect text that
    consists of random keystrokes, adversarial noise, or otherwise
    non-meaningful sequences. Supports both Hebrew and English input.

    Higher threshold values are more permissive (less likely to flag);
    lower values are stricter (more likely to flag borderline gibberish).

    Args:
        threshold: Gibberish probability score above which text is flagged.
            Must be in [0.0, 1.0]. Defaults to 0.7.
        action: Action to take when gibberish is detected.
            Defaults to BLOCK.

    Raises:
        ValueError: If threshold is outside the valid range [0.0, 1.0].
    """

    def __init__(
        self,
        threshold: float = 0.7,
        action: Action = Action.BLOCK,
    ) -> None:
        if not (0.0 <= threshold <= 1.0):
            raise ValueError(
                f"GibberishScanner threshold must be in [0.0, 1.0], got {threshold!r}."
            )
        self._threshold = threshold
        self._action = action

    def to_guardline_spec(self) -> dict:
        """Return a flat guardline spec dict for this scanner configuration."""
        return {
            "name": "GibberishScanner",
            "action": str(self._action),
            "threshold": self._threshold,
            "level": 2,
        }
